ENH: provide Time::NewGlobalTime factory methods (#3007)

- avoids clutter of argList::envGlobalPath() ...

ENH: allow temporary overwriting of output writeFormat

- allows switching for particular output routines

COMP: explicitly use TimePaths methods with Time

- this simplifies any overloading done at a later stage

applications/test/rawIOField/Test-rawIOField.C

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2022 OpenCFD Ltd.
+    Copyright (C) 2022-2023 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -122,11 +122,10 @@ int main(int argc, char *argv[])
     // Fallback (eg, no runTime)
     if (!timePtr.good())
     {
-        timePtr.reset(Time::New(argList::envGlobalPath()));
+        timePtr.reset(Time::NewGlobalTime());
     }
 
-
+    const auto& tm = *timePtr;
-    const auto& tm = timePtr();
 
     fileName resolvedName(inputName);
     resolvedName.toAbsolute();

applications/test/surface-sampling/mydebugSurfaceWriter.C

@@ -317,7 +317,11 @@ Foam::fileName Foam::surfaceWriters::mydebugWriter::write()
 
     if (enableWrite_)
     {
+        #if (OPENFOAM <= 2306)
         dummyTimePtr = Time::New(argList::envGlobalPath());
+        #else
+        dummyTimePtr = Time::NewGlobalTime();
+        #endif
     }
     else if (verbose_)
     {
@@ -392,7 +396,11 @@ Foam::fileName Foam::surfaceWriters::mydebugWriter::writeTemplate
 
     if (enableWrite_)
     {
+        #if (OPENFOAM <= 2306)
         dummyTimePtr = Time::New(argList::envGlobalPath());
+        #else
+        dummyTimePtr = Time::NewGlobalTime();
+        #endif
     }
     else if (verbose_)
     {

src/OpenFOAM/Make/files

@@ -395,6 +395,7 @@ $(Time)/TimePaths.C
 $(Time)/TimeState.C
 $(Time)/Time.C
 $(Time)/TimeIO.C
+$(Time)/TimeNew.C
 $(Time)/subCycleTime.C
 $(Time)/subLoopTime.C
 $(Time)/timeSelector.C

src/OpenFOAM/db/Time/Time.C

@@ -690,48 +690,6 @@ Foam::Time::Time
 }
 
 
-// * * * * * * * * * * * * * * * * Selectors * * * * * * * * * * * * * * * * //
-
-Foam::autoPtr<Foam::Time> Foam::Time::New()
-{
-    return
-        autoPtr<Time>::New
-        (
-            fileName("."),  // root-path
-            fileName("."),  // case-name
-            false,          // No enableFunctionObjects
-            false           // No enableLibs
-        );
-}
-
-
-Foam::autoPtr<Foam::Time> Foam::Time::New(const fileName& caseDir)
-{
-    return
-        autoPtr<Time>::New
-        (
-            caseDir.path(), // root-path
-            caseDir.name(), // case-name
-            false,          // No enableFunctionObjects
-            false           // No enableLibs
-        );
-}
-
-
-Foam::autoPtr<Foam::Time> Foam::Time::New(const argList& args)
-{
-    return
-        autoPtr<Time>::New
-        (
-            Time::controlDictName,
-            args,
-            false,          // No enableFunctionObjects
-            false,          // No enableLibs
-            IOobjectOption::MUST_READ  // No re-reading
-        );
-}
-
-
 // * * * * * * * * * * * * * * * * Destructor  * * * * * * * * * * * * * * * //
 
 Foam::Time::~Time()

src/OpenFOAM/db/Time/Time.H

@@ -348,7 +348,7 @@ public:
         );
 
 
-    // Selectors
+    // Factory Methods
 
         //- Construct (dummy) Time - no functionObjects or libraries
         static autoPtr<Time> New();
@@ -359,6 +359,15 @@ public:
         //- Construct (dummy) Time - no functionObjects or libraries
         static autoPtr<Time> New(const argList& args);
 
+        //- Construct (dummy) global Time - no functionObjects or libraries,
+        //- using the global path information stored in the FOAM_CASE
+        //- environment. See argList::envGlobalPath()
+        static autoPtr<Time> NewGlobalTime();
+
+        //- Construct (dummy) global Time - no functionObjects or libraries,
+        //- using the global path information from the referenced Time.
+        static autoPtr<Time> NewGlobalTime(const Time& runTime);
+
 
     //- Destructor
     virtual ~Time();
@@ -376,119 +385,136 @@ public:
         static word timeName(const scalar t, const int precision = precision_);
 
 
-        // Database Functions
+    // Database names and paths
 
-            //- Return name from objectRegistry and not TimePaths
+        //- Use name from objectRegistry, not TimePaths
-            using objectRegistry::name;
+        using objectRegistry::name;
 
-            //- Return root path
+        //- Return the rootPath
-            using TimePaths::rootPath;
+        using TimePaths::rootPath;
 
-            //- Return case name
+        //- Return global case name
-            using TimePaths::caseName;
+        using TimePaths::globalCaseName;
 
-            //- Return path
+        //- Return case name
-            fileName path() const
+        using TimePaths::caseName;
-            {
-                return rootPath()/caseName();
-            }
 
-            //- Return read access to the controlDict dictionary
+        //- Return path = rootPath/caseName. Same as TimePaths::path()
-            const dictionary& controlDict() const noexcept
+        fileName path() const
-            {
+        {
-                return controlDict_;
+            return TimePaths::rootPath()/TimePaths::caseName();
-            }
+        }
 
-            virtual const fileName& dbDir() const
+        //- Return global path for the case = rootPath/globalCaseName.
-            {
+        //- Same as TimePaths::globalPath()
-                return fileName::null;
+        fileName globalPath() const
-            }
+        {
+            return TimePaths::rootPath()/TimePaths::globalCaseName();
+        }
 
-            //- Return current time path
+        //- Return current time path = path/timeName
-            fileName timePath() const
+        fileName timePath() const
-            {
+        {
-                return path()/timeName();
+            return TimePaths::path()/TimeState::timeName();
-            }
+        }
 
-            //- The write stream option (format, compression, version)
+        //- Return current time global path = globalPath/timeName
-            IOstreamOption writeStreamOption() const noexcept
+        fileName globalTimePath() const
-            {
+        {
-                return writeStreamOption_;
+            return TimePaths::globalPath()/TimeState::timeName();
-            }
+        }
 
-            //- The write stream format
-            IOstreamOption::streamFormat writeFormat() const noexcept
-            {
-                return writeStreamOption_.format();
-            }
 
-            //- The write stream compression
+    // Database Functions
-            IOstreamOption::compressionType writeCompression() const noexcept
-            {
-                return writeStreamOption_.compression();
-            }
 
-            //- The write stream version
+        //- Return read access to the controlDict dictionary
-            IOstreamOption::versionNumber writeVersion() const noexcept
+        const dictionary& controlDict() const noexcept { return controlDict_; }
-            {
-                return writeStreamOption_.version();
-            }
 
-            //- Default graph format
+        virtual const fileName& dbDir() const { return fileName::null; }
-            const word& graphFormat() const noexcept
-            {
-                return graphFormat_;
-            }
 
-            //- Supports re-reading
+        //- Get write stream option (format, compression, version)
-            Switch runTimeModifiable() const noexcept
+        inline IOstreamOption writeStreamOption() const noexcept;
-            {
-                return runTimeModifiable_;
-            }
 
-            //- Set re-reading support on/off (use with caution).
+        //- Get write stream format
-            //  \return the previous value
+        inline IOstreamOption::streamFormat writeFormat() const noexcept;
-            Switch runTimeModifiable(const Switch sw) noexcept
-            {
-                Switch old(runTimeModifiable_);
-                runTimeModifiable_ = sw;
-                return old;
-            }
 
-            //- Read control dictionary, update controls and time
+        //- Set the write stream format and return the previous value.
-            virtual bool read();
+        //  This change will only effective until the next readModified.
+        //  As a side-effect (eg, changing from ASCII to BINARY)
+        //  it may also disable compression
+        inline IOstreamOption::streamFormat
+        writeFormat(IOstreamOption::streamFormat fmt) noexcept;
 
-            //- Read the objects that have been modified
+        //- Get the write stream compression
-            void readModifiedObjects();
+        inline IOstreamOption::compressionType writeCompression()
+        const noexcept;
 
-            //- Return time instance (location) of \em dir that contains
+        //- Get the write stream version
-            //- the file \em name (eg, used in reading mesh data).
+        inline IOstreamOption::versionNumber writeVersion() const noexcept;
-            //  When \em is empty, searches for directory \em dir only.
-            //  Does not search beyond stopInstance (if set) or \em constant.
-            //
-            //  \note If the instance cannot be found, returns the
-            //  stopInstance (if set and reached) or \em constant.
-            //  FatalError if it cannot be found and readOpt is
-            //  (MUST_READ or READ_MODIFIED).
-            word findInstance
-            (
-                const fileName& dir,
-                const word& name = word::null,
-                IOobjectOption::readOption rOpt = IOobjectOption::MUST_READ,
-                const word& stopInstance = word::null
-            ) const;
 
-            //- Search the case for the time directory path
+        //- Default graph format
-            //- corresponding to the given instance
+        const word& graphFormat() const noexcept { return graphFormat_; }
-            word findInstancePath
-            (
-                const fileName& directory,
-                const instant& t
-            ) const;
 
-            //- Search the case for the time directory path
+
-            //- corresponding to the given instance
+    // Reading
-            word findInstancePath(const instant& t) const;
+
+        //- Supports re-reading
+        Switch runTimeModifiable() const noexcept
+        {
+            return runTimeModifiable_;
+        }
+
+        //- Set re-reading support on/off (use with caution).
+        //  \return the previous value
+        Switch runTimeModifiable(Switch sw) noexcept
+        {
+            Switch old(runTimeModifiable_);
+            runTimeModifiable_ = sw;
+            return old;
+        }
+
+        //- Read control dictionary, update controls and time
+        virtual bool read();
+
+        //- Read the objects that have been modified
+        void readModifiedObjects();
+
+
+    // Searching
+
+        //- Return time instance (location) of \em dir that contains
+        //- the file \em name (eg, used in reading mesh data).
+        //  When \em is empty, searches for directory \em dir only.
+        //  Does not search beyond stopInstance (if set) or \em constant.
+        //
+        //  \note If the instance cannot be found, returns the
+        //  stopInstance (if set and reached) or \em constant.
+        //  FatalError if it cannot be found and readOpt is
+        //  (MUST_READ or READ_MODIFIED).
+        word findInstance
+        (
+            const fileName& dir,
+            const word& name = word::null,
+            IOobjectOption::readOption rOpt = IOobjectOption::MUST_READ,
+            const word& stopInstance = word::null
+        ) const;
+
+        //- Search the case for the time directory path
+        //- corresponding to the given instance
+        word findInstancePath
+        (
+            const fileName& directory,
+            const instant& t
+        ) const;
+
+        //- Search the case for the time directory path
+        //- corresponding to the given instance
+        word findInstancePath(const instant& t) const;
+
+
+    // Member Functions
+
+        // Writing
 
             //- Write time dictionary to the \<time\>/uniform directory
             virtual bool writeTimeDict() const;

src/OpenFOAM/db/Time/TimeI.H

@@ -117,4 +117,47 @@ inline Foam::Time::Time
 {}
 
 
+// * * * * * * * * * * * * * * * Member Functions  * * * * * * * * * * * * * //
+
+inline Foam::IOstreamOption
+Foam::Time::writeStreamOption() const noexcept
+{
+    return writeStreamOption_;
+}
+
+
+inline Foam::IOstreamOption::streamFormat
+Foam::Time::writeFormat() const noexcept
+{
+    return writeStreamOption_.format();
+}
+
+
+inline Foam::IOstreamOption::streamFormat
+Foam::Time::writeFormat(IOstreamOption::streamFormat fmt) noexcept
+{
+    auto old(writeStreamOption_.format(fmt));
+    if (writeStreamOption_.format() != IOstreamOption::ASCII)
+    {
+        // Disable output compression for non-ASCII
+        writeStreamOption_.compression(IOstreamOption::UNCOMPRESSED);
+    }
+    return old;
+}
+
+
+inline Foam::IOstreamOption::compressionType
+Foam::Time::writeCompression() const noexcept
+{
+    return writeStreamOption_.compression();
+}
+
+
+inline Foam::IOstreamOption::versionNumber
+Foam::Time::writeVersion() const noexcept
+{
+    return writeStreamOption_.version();
+}
+
+
 // ************************************************************************* //

src/OpenFOAM/db/Time/TimeIO.C

@@ -355,11 +355,15 @@ void Foam::Time::readDict()
     // Adjust the TimeState name
     dimensionedScalar::name() = timeName(value());
 
+    // Specifying the write version doesn't make sense (2023-10)
     if (controlDict_.found("writeVersion"))
     {
         writeStreamOption_.version(controlDict_.get<token>("writeVersion"));
     }
 
+    // FUTURE? optional control to support command-line option to
+    // set the write format and ignore this dictionary entry.
+
     if (controlDict_.found("writeFormat"))
     {
         writeStreamOption_.format(controlDict_.get<word>("writeFormat"));

src/OpenFOAM/db/Time/TimeNew.C

@@ -0,0 +1,115 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     |
+    \\  /    A nd           | www.openfoam.com
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+    Copyright (C) 2019-2023 OpenCFD Ltd.
+-------------------------------------------------------------------------------
+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 "Time.H"
+#include "argList.H"
+
+// * * * * * * * * * * * * * * * * Selectors * * * * * * * * * * * * * * * * //
+
+Foam::autoPtr<Foam::Time> Foam::Time::New()
+{
+    return autoPtr<Time>::New
+    (
+        fileName("."),  // root-path
+        fileName("."),  // case-name
+        false,          // No enableFunctionObjects
+        false           // No enableLibs
+    );
+}
+
+// FUTURE?
+// Foam::autoPtr<Foam::Time> Foam::Time::New(const Time& runTime)
+// {
+//     fileName caseDir(runTime.path());
+//     caseDir.toAbsolute();
+//
+//     return autoPtr<Time>::New
+//     (
+//         caseDir.path(), // root-path
+//         caseDir.name(), // case-name
+//         false,          // No enableFunctionObjects
+//         false           // No enableLibs
+//     );
+// }
+
+
+Foam::autoPtr<Foam::Time> Foam::Time::New(const fileName& caseDir)
+{
+    return autoPtr<Time>::New
+    (
+        caseDir.path(), // root-path
+        caseDir.name(), // case-name
+        false,          // No enableFunctionObjects
+        false           // No enableLibs
+    );
+}
+
+
+Foam::autoPtr<Foam::Time> Foam::Time::New(const argList& args)
+{
+    return autoPtr<Time>::New
+    (
+        Time::controlDictName,
+        args,
+        false,          // No enableFunctionObjects
+        false,          // No enableLibs
+        IOobjectOption::MUST_READ  // No re-reading
+    );
+}
+
+
+Foam::autoPtr<Foam::Time> Foam::Time::NewGlobalTime()
+{
+    fileName caseDir(argList::envGlobalPath());
+    caseDir.toAbsolute();
+
+    return autoPtr<Time>::New
+    (
+        caseDir.path(), // root-path
+        caseDir.name(), // case-name
+        false,          // No enableFunctionObjects
+        false           // No enableLibs
+    );
+}
+
+
+Foam::autoPtr<Foam::Time> Foam::Time::NewGlobalTime(const Time& runTime)
+{
+    fileName caseDir(runTime.globalPath());
+    caseDir.toAbsolute();
+
+    return autoPtr<Time>::New
+    (
+        caseDir.path(), // root-path
+        caseDir.name(), // case-name
+        false,          // No enableFunctionObjects
+        false           // No enableLibs
+    );
+}
+
+
+// ************************************************************************* //

src/OpenFOAM/db/Time/TimePaths.H

@@ -133,10 +133,10 @@ public:
         //- The case name for modification (use with caution)
         inline fileName& caseName() noexcept;
 
-        //- Return path for the case
+        //- Return path for the case = rootPath/caseName
         inline fileName path() const;
 
-        //- Return global path for the case
+        //- Return global path for the case = rootPath/globalCaseName
         inline fileName globalPath() const;
 
         //- Return the input relative to the globalPath by stripping off

src/OpenFOAM/primitives/strings/fileName/fileName.C

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2017 OpenFOAM Foundation
-    Copyright (C) 2016-2022 OpenCFD Ltd.
+    Copyright (C) 2016-2023 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -376,13 +376,15 @@ Foam::fileName::Type Foam::fileName::type
 
 Foam::fileName& Foam::fileName::toAbsolute()
 {
-    if (!isAbsolute(*this))
+    fileName& f = *this;
+
+    if (!f.isAbsolute())
     {
-        fileName& f = *this;
+        f = Foam::cwd()/f;
-        f = cwd()/f;
-        f.clean();  // Remove unneeded ".."
     }
 
+    f.clean();  // Remove unneeded ".."
+
     return *this;
 }
 

src/OpenFOAM/primitives/strings/fileName/fileName.H

@@ -6,7 +6,7 @@
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
     Copyright (C) 2011-2017 OpenFOAM Foundation
-    Copyright (C) 2016-2022 OpenCFD Ltd.
+    Copyright (C) 2016-2023 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -41,6 +41,7 @@ Description
 
 SourceFiles
     fileName.C
+    fileNameI.H
     fileNameIO.C
 
 \*---------------------------------------------------------------------------*/
@@ -242,7 +243,8 @@ public:
         //- or (windows-only) with a filesystem-root
         inline bool isAbsolute() const;
 
-        //- Convert from relative to absolute
+        //- Convert from relative to absolute.
+        //  As a side-effect, always performs a clean() to remove "/./" etc
         fileName& toAbsolute();
 
         //- Return true if string ends with "~", ".bak", ".old", ".save"

src/parallel/reconstruct/faReconstruct/faMeshReconstructor.C

@@ -454,7 +454,7 @@ void Foam::faMeshReconstructor::createMesh()
     const Time& runTime = procMesh_.thisDb().time();
 
     // Time for non-parallel case (w/o functionObjects or libs)
-    serialRunTime_ = Time::New(runTime.globalPath().toAbsolute());
+    serialRunTime_ = Time::NewGlobalTime(runTime);
 
 
     // Trivial polyMesh only containing points and faces.

src/surfMesh/readers/boundary/boundaryDataSurfaceReader.C

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2022 OpenCFD Ltd.
+    Copyright (C) 2022-2023 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -27,7 +27,6 @@ License
 
 #include "boundaryDataSurfaceReader.H"
 #include "rawIOField.H"
-#include "argList.H"
 #include "Time.H"
 #include "addToRunTimeSelectionTable.H"
 
@@ -92,7 +91,7 @@ Foam::pointField Foam::boundaryDataSurfaceReader::readPoints
     const word& pointsName
 )
 {
-    refPtr<Time> timePtr(Time::New(argList::envGlobalPath()));
+    refPtr<Time> timePtr(Time::NewGlobalTime());
 
     return readPoints(*timePtr, dirName, pointsName);
 }

src/surfMesh/readers/boundary/boundaryDataSurfaceReaderTemplates.C

@@ -5,7 +5,7 @@
     \\  /    A nd           | www.openfoam.com
      \\/     M anipulation  |
 -------------------------------------------------------------------------------
-    Copyright (C) 2022 OpenCFD Ltd.
+    Copyright (C) 2022-2023 OpenCFD Ltd.
 -------------------------------------------------------------------------------
 License
     This file is part of OpenFOAM.
@@ -27,7 +27,6 @@ License
 
 #include "boundaryDataSurfaceReader.H"
 #include "rawIOField.H"
-#include "argList.H"
 #include "Time.H"
 
 // * * * * * * * * * * * * * Static Member Functions * * * * * * * * * * * * //
@@ -86,7 +85,7 @@ Foam::boundaryDataSurfaceReader::readField
     Type& avg
 )
 {
-    refPtr<Time> timePtr(Time::New(argList::envGlobalPath()));
+    refPtr<Time> timePtr(Time::NewGlobalTime());
 
     return readField<Type>(*timePtr, baseDir, timeDir, fieldName, avg);
 }

src/surfMesh/writers/boundary/boundaryDataSurfaceWriter.C

@@ -27,7 +27,6 @@ License
 \*---------------------------------------------------------------------------*/
 
 #include "boundaryDataSurfaceWriter.H"
-#include "argList.H"
 #include "OFstream.H"
 #include "OSspecific.H"
 #include "IOmanip.H"
@@ -203,7 +202,7 @@ Foam::fileName Foam::surfaceWriters::boundaryDataWriter::write()
     fileName surfaceDir = outputPath_;
 
     // Dummy Time to use as objectRegistry
-    refPtr<Time> timePtr(Time::New(argList::envGlobalPath()));
+    refPtr<Time> timePtr(Time::NewGlobalTime());
 
     // const meshedSurf& surf = surface();
     const meshedSurfRef& surf = adjustSurface();
@@ -265,7 +264,7 @@ Foam::fileName Foam::surfaceWriters::boundaryDataWriter::writeTemplate
 
 
     // Dummy Time to use as objectRegistry
-    refPtr<Time> timePtr(Time::New(argList::envGlobalPath()));
+    refPtr<Time> timePtr(Time::NewGlobalTime());
 
     // const meshedSurf& surf = surface();
     const meshedSurfRef& surf = adjustSurface();

src/surfMesh/writers/debug/debugSurfaceWriter.C

@@ -27,7 +27,6 @@ License
 
 #include "debugSurfaceWriter.H"
 #include "globalIndex.H"
-#include "argList.H"
 #include "OFstream.H"
 #include "OSspecific.H"
 #include "IOmanip.H"
@@ -212,7 +211,7 @@ Foam::fileName Foam::surfaceWriters::debugWriter::write()
 
     if (enableWrite_)
     {
-        dummyTimePtr = Time::New(argList::envGlobalPath());
+        dummyTimePtr = Time::NewGlobalTime();
     }
     else if (verbose_)
     {
@@ -287,7 +286,7 @@ Foam::fileName Foam::surfaceWriters::debugWriter::writeTemplate
 
     if (enableWrite_)
     {
-        dummyTimePtr = Time::New(argList::envGlobalPath());
+        dummyTimePtr = Time::NewGlobalTime();
     }
     else if (verbose_)
     {