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/test/IOField/Test-IOField.cxx

@@ -188,8 +188,6 @@ int main(int argc, char *argv[])
     argList::addBoolOption("label", "Use label for tests (default)");
     argList::addBoolOption("ref", "Test writing by ref");
 
-    #include "addTimeOptions.H"
-
     #include "setRootCase.H"
     #include "createTime.H"
     #include "createPolyMesh.H"
@@ -280,7 +278,6 @@ int main(int argc, char *argv[])
         {
             IOFieldRef<vector>(ioOutput, mesh.points()).write();
         }
-
     }
 
 

applications/test/PatchTools/Test-PatchTools.C

@@ -201,7 +201,6 @@ using namespace Foam;
 
 int main(int argc, char *argv[])
 {
-    #include "addTimeOptions.H"
     argList::addArgument("patch");
     #include "setRootCase.H"
     #include "createTime.H"

applications/test/checkDecomposePar/Test-checkDecomposePar.C

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2017-2023 OpenCFD Ltd.
+    Copyright (C) 2017-2024 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -24,7 +24,7 @@ License
     along with OpenFOAM.  If not, see <http://www.gnu.org/licenses/>.
 
 Application
-    checkDecomposePar
+    Test-checkDecomposePar
 
 Group
     grpParallelUtilities
@@ -35,8 +35,9 @@ Description
 
 \*---------------------------------------------------------------------------*/
 
-#include "OSspecific.H"
+#include "argList.H"
-#include "fvCFD.H"
+#include "timeSelector.H"
+#include "polyMesh.H"
 #include "cpuTime.H"
 #include "IFstream.H"
 #include "regionProperties.H"
@@ -44,10 +45,14 @@ Description
 #include "decompositionInformation.H"
 #include "decompositionModel.H"
 
+using namespace Foam;
+
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
 int main(int argc, char *argv[])
 {
+    timeSelector::addOptions_singleTime();  // Single-time options
+
     argList::addNote
     (
         "Check decomposition from kaffpa (KaHIP) output"
@@ -65,9 +70,6 @@ int main(int argc, char *argv[])
 
     argList::addArgument("kaffpa-output-file");
 
-    // Include explicit constant options, have zero from time range
-    timeSelector::addOptions(true, false);
-
     #include "setRootCase.H"
 
     const auto decompFile = args.get<fileName>(1);
@@ -75,8 +77,8 @@ int main(int argc, char *argv[])
     // Set time from database
     #include "createTime.H"
 
-    // Allow override of time
+    // Allow override of time from specified time options, or no-op
-    instantList times = timeSelector::selectIfPresent(runTime, args);
+    timeSelector::setTimeIfPresent(runTime, args);
 
     // Allow override of decomposeParDict location
     const fileName decompDictFile =
@@ -95,7 +97,7 @@ int main(int argc, char *argv[])
         Info<< "\n\nDecomposing mesh " << regionName << nl << endl;
         Info<< "Create mesh..." << flush;
 
-        fvMesh mesh
+        polyMesh mesh
         (
             IOobject
             (
@@ -111,7 +113,7 @@ int main(int argc, char *argv[])
         Info<< " nCells = " << mesh.nCells() << endl;
 
         // Expected format is a simple ASCII list
-        cellToProc.setSize(mesh.nCells());
+        cellToProc.resize(mesh.nCells());
         {
             IFstream is(decompFile);
 

applications/test/extendedStencil/Test-ExtendedStencil.C

@@ -32,6 +32,7 @@ Description
 \*---------------------------------------------------------------------------*/
 
 #include "argList.H"
+#include "timeSelector.H"
 #include "fvMesh.H"
 #include "volFields.H"
 #include "Time.H"
@@ -126,14 +127,14 @@ void writeStencilStats(const labelListList& stencil)
 
 int main(int argc, char *argv[])
 {
-    #include "addTimeOptions.H"
+    timeSelector::addOptions_singleTime();  // Single-time options
+
     #include "setRootCase.H"
     #include "createTime.H"
 
-    // Get times list
+    // Set time from specified time options, or force start from Time=0
-    instantList Times = runTime.times();
+    timeSelector::setTimeIfPresent(runTime, args, true);
-    #include "checkTimeOptions.H"
+
-    runTime.setTime(Times[startTime], startTime);
     #include "createMesh.H"
 
     // Force calculation of extended edge addressing

applications/test/extendedStencil/Test-ExtendedStencil2.C

@@ -32,6 +32,7 @@ Description
 \*---------------------------------------------------------------------------*/
 
 #include "argList.H"
+#include "timeSelector.H"
 #include "fvMesh.H"
 #include "volFields.H"
 #include "surfaceFields.H"
@@ -107,14 +108,16 @@ void writeStencilStats(const labelListList& stencil)
 
 int main(int argc, char *argv[])
 {
-    #include "addTimeOptions.H"
+    argList::noFunctionObjects();           // Never use function objects
+
+    timeSelector::addOptions_singleTime();  // Single-time options
+
     #include "setRootCase.H"
     #include "createTime.H"
 
-    // Get times list
+    // Set time from specified time options, or force start from Time=0
-    instantList Times = runTime.times();
+    timeSelector::setTimeIfPresent(runTime, args, true);
-    #include "checkTimeOptions.H"
+
-    runTime.setTime(Times[startTime], startTime);
     #include "createMesh.H"
 
 

applications/test/fieldMapping/Make/options

@@ -5,4 +5,5 @@ EXE_INC = \
 
 EXE_LIBS = \
     -lfiniteVolume \
+    -lmeshTools \
     -ldynamicMesh

applications/test/fieldMapping/Test-fieldMapping.C

@@ -32,6 +32,7 @@ Description
 \*---------------------------------------------------------------------------*/
 
 #include "argList.H"
+#include "timeSelector.H"
 #include "fvMesh.H"
 #include "volFields.H"
 #include "Time.H"
@@ -51,22 +52,33 @@ using namespace Foam;
 
 int main(int argc, char *argv[])
 {
-    #include "addTimeOptions.H"
+    timeSelector::addOptions_singleTime();  // Single-time options
-    argList::addArgument("inflate (true|false)");
+
+    argList::addBoolOption
+    (
+        "inflate",
+        "Use inflation/deflation for deleting cells"
+    );
+
     #include "setRootCase.H"
     #include "createTime.H"
+
+    // Allow override of time from specified time options, or no-op
+    timeSelector::setTimeIfPresent(runTime, args);
+
     #include "createMesh.H"
 
-    const Switch inflate(args[1]);
+    const bool inflate = args.found("inflate");
 
     if (inflate)
     {
-        Info<< "Deleting cells using inflation/deflation" << nl << endl;
+        Info<< "Deleting cells using inflation/deflation"
+            << nl << endl;
     }
     else
     {
-        Info<< "Deleting cells, introducing points at new position" << nl
+        Info<< "Deleting cells, introducing points at new position"
-            << endl;
+            << nl << endl;
     }
 
 

applications/test/hexRef8/Make/options

@@ -5,4 +5,5 @@ EXE_INC = \
 
 EXE_LIBS = \
     -lfiniteVolume \
+    -lmeshTools \
     -ldynamicMesh

applications/test/hexRef8/Test-hexRef8.C

@@ -33,6 +33,7 @@ Description
 \*---------------------------------------------------------------------------*/
 
 #include "argList.H"
+#include "timeSelector.H"
 #include "Time.H"
 #include "volFields.H"
 #include "surfaceFields.H"
@@ -52,21 +53,28 @@ using namespace Foam;
 // Main program:
 int main(int argc, char *argv[])
 {
-    #include "addTimeOptions.H"
+    timeSelector::addOptions_singleTime();  // Single-time options
-    argList::addArgument("inflate (true|false)");
+
+    argList::addBoolOption
+    (
+        "inflate",
+        "Use inflation/deflation for splitting/deleting cells"
+    );
+
     #include "setRootCase.H"
     #include "createTime.H"
+
+    // Allow override of time from specified time options, or no-op
+    timeSelector::setTimeIfPresent(runTime, args);
+
     #include "createMesh.H"
 
-
+    const bool inflate = args.found("inflate");
-    const pointConstraints& pc = pointConstraints::New(pointMesh::New(mesh));
-
-    const Switch inflate(args[1]);
 
     if (inflate)
     {
-        Info<< "Splitting/deleting cells using inflation/deflation" << nl
+        Info<< "Splitting/deleting cells using inflation/deflation"
-            << endl;
+            << nl << endl;
     }
     else
     {
@@ -75,6 +83,8 @@ int main(int argc, char *argv[])
     }
 
 
+    const pointConstraints& pc = pointConstraints::New(pointMesh::New(mesh));
+
     Random rndGen(0);
 
 

applications/test/mappedPatch/Test-MappedPatch.C

@@ -51,7 +51,6 @@ using namespace Foam;
 
 int main(int argc, char *argv[])
 {
-    #include "addTimeOptions.H"
     #include "setRootCase.H"
     #include "createTime.H"
     #include "createMesh.H"

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
+    // Set time from specified time options, or force start from Time=0
-    instantList Times = runTime.times();
+    timeSelector::setTimeIfPresent(runTime, args, true);
-
-    // Set startTime depending on -time and -latestTime options
-    #include "checkTimeOptions.H"
-
-    runTime.setTime(Times[startTime], startTime);
 
+    // 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
+    // Allow override of time from specified time options, or no-op
-    (void)timeSelector::selectIfPresent(runTime, args);
+    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();
+    // Set time from specified time options, or force start from Time=0
-    #include "checkTimeOptions.H"
+    timeSelector::setTimeIfPresent(runTime, args, true);
-    runTime.setTime(Times[startTime], startTime);
 
     // 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;

src/OpenFOAM/db/Time/timeSelector.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2017 OpenFOAM Foundation
-    Copyright (C) 2018-2022 OpenCFD Ltd.
+    Copyright (C) 2018-2024 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -115,7 +115,7 @@ void Foam::timeSelector::addOptions
         argList::addBoolOption
         (
             "constant",
-            "Include the 'constant/' dir in the times list"
+            "Include 'constant/' dir in the times list"
         );
     }
     if (withZero)
@@ -123,13 +123,13 @@ void Foam::timeSelector::addOptions
         argList::addBoolOption
         (
             "withZero",
-            "Include the '0/' dir in the times list"
+            "Include '0/' dir in the times list"
         );
     }
     argList::addBoolOption
     (
         "noZero",
-        string("Exclude the '0/' dir from the times list")
+        string("Exclude '0/' dir from the times list")
       + (
             withZero
           ? ", has precedence over the -withZero option"
@@ -150,6 +150,32 @@ void Foam::timeSelector::addOptions
 }
 
 
+void Foam::timeSelector::addOptions_singleTime()
+{
+    argList::addBoolOption
+    (
+        "constant",
+        "Include 'constant/' dir in the times"
+    );
+    argList::addBoolOption
+    (
+        "noZero",
+        "Exclude '0/' dir from the times (currently ignored)"
+    );
+    argList::addBoolOption
+    (
+        "latestTime",
+        "Select the latest time"
+    );
+    argList::addOption
+    (
+        "time",
+        "value",
+        "Select the nearest time to the specified value"
+    );
+}
+
+
 Foam::instantList Foam::timeSelector::select
 (
     const instantList& times,
@@ -291,4 +317,77 @@ Foam::instantList Foam::timeSelector::selectIfPresent
 }
 
 
+bool Foam::timeSelector::setTimeIfPresent
+(
+    Time& runTime,
+    const argList& args,
+    const bool forceInitial
+)
+{
+    label timei = -1;
+    instantList times;
+
+    if
+    (
+        forceInitial
+     || args.found("constant")
+     || args.found("latestTime")
+     || args.found("time")
+        // Currently ignoring -noZero, -withZero
+    )
+    {
+        // Get times list
+        times = runTime.times();
+    }
+
+    if (times.size())
+    {
+        // Start from first time (eg, for -constant or forced)
+        timei = 0;
+
+        // Determine latestTime selection (if any)
+        // This must appear before the -time option processing
+        if (args.found("latestTime"))
+        {
+            timei = times.size() - 1;
+        }
+        else if (args.found("time"))
+        {
+            const scalar target = args.get<scalar>("time");
+
+            timei = TimePaths::findClosestTimeIndex(times, target);
+        }
+
+
+        // Avoid "constant" unless specifically requested with -constant,
+        // and the -constant option is actually an expected option
+
+        if
+        (
+            (timei >= 0 && timei < times.size()-1)
+         && times[timei].name() == "constant"
+         && (argList::validOptions.found("constant") && !args.found("constant"))
+        )
+        {
+            ++timei;
+        }
+    }
+
+
+    if (timei >= 0 && timei < times.size())
+    {
+        // Specified a timeSelector option, or forceInitial.
+        // Set the runTime accordingly.
+
+        runTime.setTime(times[timei], timei);
+        return true;
+    }
+    else
+    {
+        // No timeSelector option specified. Do not change runTime.
+        return false;
+    }
+}
+
+
 // ************************************************************************* //

src/OpenFOAM/db/Time/timeSelector.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2015 OpenFOAM Foundation
-    Copyright (C) 2018-2022 OpenCFD Ltd.
+    Copyright (C) 2018-2024 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -28,14 +28,13 @@ Class
     Foam::timeSelector
 
 Description
-    A List of scalarRange for selecting times.
-
     The timeSelector provides a convenient means of selecting multiple
-    times. A typical use would be the following:
+    times.
 
+    A typical use would be the following:
     \verbatim
     timeSelector::addOptions();
-    // add other options
+    ...
     #include "setRootCase.H"
     #include "createTime.H"
     instantList timeDirs = timeSelector::select0(runTime, args);
@@ -46,11 +45,11 @@ Description
     }
     \endverbatim
 
-    The result program would receive \b -time, \b -latestTime, \b -constant
+    With the \c addOptions() method, application receives
-    and \b -noZero options. The \b -constant option explicitly includes the
+    \b -time, \b -latestTime, \b -constant and \b -noZero options.
+    The \b -constant option explicitly includes the
     \c constant/ directory in the time list and the \b -noZero option
     explicitly excludes the \c 0/ directory from the time list.
-
     There may however also be many cases in which neither the \c constant/
     directory nor the \c 0/ directory contain particularly relevant
     information. This might occur, for example, when post-processing
@@ -66,6 +65,25 @@ Description
     \c 0/ directory from being included in the default time range and in the
     \b -latestTime selection.
 
+    It is also possible to use the timeSelector for setting a single time.
+    Typical use would be the following:
+
+    \verbatim
+    timeSelector::addOptions_singleTime();
+    ...
+    #include "setRootCase.H"
+    #include "createTime.H"
+    timeSelector::setTimeIfPresent(runTime, args);
+    \endverbatim
+
+    With the \c addOptions_singleTime() method, application receives
+    \b -time, \b -latestTime, \b -constant options. In the case,
+    the \b -time option is intended to be a single value and not include
+    any ranges.
+
+    The subsequent call to \c setTimeIfPresent() will scan the arguments
+    for relevant time options and use them to set the time.
+
 SourceFiles
     timeSelector.C
 
@@ -135,6 +153,14 @@ public:
 
         //- Add timeSelector options to argList::validOptions
         //
+        //  \par Options added:
+        //  - \c -constant
+        //  - \c -time
+        //  - \c -latestTime
+        //  - \c -noZero
+        //  - \c -withZero
+        //  .
+        //
         // \param constant
         //   Add the \b -constant option to include the \c constant/ directory
         //
@@ -150,6 +176,16 @@ public:
             const bool withZero=false
         );
 
+        //- Add single-time timeSelector options to argList::validOptions()
+        //
+        //  \par Options added:
+        //  - \c -constant
+        //  - \c -time
+        //  - \c -latestTime
+        //  - \c -noZero  (ignored)
+        //  .
+        static void addOptions_singleTime();
+
         //- Return the set of times selected based on the argList options
         static instantList select
         (
@@ -167,14 +203,25 @@ public:
             const argList& args
         );
 
-        //- If any time option provided return the set of times (as select0)
+        //- If any time option provided return the set of times -
-        //- otherwise return just the current time.
+        //- as per select0() - otherwise return just the current time.
         //  Also set the runTime to the first instance
         static instantList selectIfPresent
         (
             Time& runTime,
             const argList& args
         );
+
+        //- Set the runTime based on \c -constant (if present),
+        //- \c -time (value), or \c -latestTime.
+        //  This method is a no-op if no relevant options have been specified.
+        static bool setTimeIfPresent
+        (
+            Time& runTime,
+            const argList& args,
+            //! Force initial time (default: 0) even if no options specified
+            const bool forceInitial = false
+        );
 };
 
 

src/OpenFOAM/include/addTimeOptions.H

@@ -22,26 +22,27 @@ Required Classes
 Foam::argList::addBoolOption
 (
     "constant",
-    "include the 'constant/' dir in the times list"
+    "Include 'constant/' dir in the times"
 );
 
 Foam::argList::addBoolOption
 (
     "latestTime",
-    "select the latest time"
+    "Select the latest time"
 );
 
 Foam::argList::addBoolOption
 (
     "noZero",
-    "exclude the '0/' dir from the times list"
+    "Exclude '0/' dir from the times"
 );
 
 Foam::argList::addOption
 (
     "time",
-    "time",
+    "value",
-    "specify a single time value to select"
+    "Select the nearest time to the specified value"
 );
 
+
 // ************************************************************************* //

src/OpenFOAM/include/checkConstantOption.H

@@ -1,3 +1,6 @@
+// Deprecated include (2024-05) - prefer timeSelector
+// ----------------------------------------------------------------------------
+
 // Unless -constant is present, skip startTime if it is "constant"
 
 if
@@ -9,3 +12,5 @@ if
 {
     ++startTime;
 }
+
+// ************************************************************************* //

src/OpenFOAM/include/checkTimeOption.H

@@ -1,13 +1,17 @@
+// Deprecated include (2024-05) - prefer timeSelector
+// ----------------------------------------------------------------------------
+
 // Check -time and -latestTime options
-
-if (args.found("time"))
-{
-    Foam::scalar timeValue = args.get<scalar>("time");
-
-    startTime = Foam::Time::findClosestTimeIndex(Times, timeValue);
-}
-
 if (args.found("latestTime"))
 {
     startTime = Times.size() - 1;
 }
+else if (args.found("time"))
+{
+    Foam::scalar timeValue = args.get<Foam::scalar>("time");
+
+    startTime = Foam::Time::findClosestTimeIndex(Times, timeValue);
+}
+
+
+// ************************************************************************* //

src/OpenFOAM/include/checkTimeOptions.H

@@ -1,3 +1,6 @@
+// Deprecated include (2024-05) - prefer timeSelector
+// ----------------------------------------------------------------------------
+
 Foam::label startTime = 0;
 
 // Unless -constant is present, skip startTime if it is "constant"
@@ -5,3 +8,5 @@ Foam::label startTime = 0;
 
 // Check -time and -latestTime options
 #include "checkTimeOption.H"
+
+// ************************************************************************* //

src/OpenFOAM/include/checkTimeOptionsNoConstant.H

@@ -1,4 +1,9 @@
+// Deprecated include (2024-05) - prefer timeSelector
+// ----------------------------------------------------------------------------
+
 Foam::label startTime = 0;
 
 // Check -time and -latestTime options
 #include "checkTimeOption.H"
+
+// ************************************************************************* //

tutorials/incompressible/lumpedPointMotion/bridge/code/polynomial-motion.C

@@ -534,7 +534,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"
 

tutorials/incompressible/lumpedPointMotion/building/code/building-motion.C

@@ -576,7 +576,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"