functionObjects: stopAtEmptyClouds: New function to end the run when clouds are empty

This function stops the run when all parcel clouds are empty.

Example of function object specification:

    stop
    {
        type            stopAtEmptyClouds;
        libs            ("liblagrangianFunctionObjects.so");

        executeControl  timeStep; // <-- Likely only to be needed if injection
        startTime       0.500001; // starts after time zero. In which case the
                                  // startTime should be slightly after the
                                  // injection start time.

        action          nextWrite;
    }

A packaged function object is also included, which permits the following
syntax to be used, either with #includeFunc in the system/controlDict,
or with the -func option to foamPostProcess:

   stopAtEmptyClouds(startTime=0.500001)

etc/caseDicts/postProcessing/lagrangian/stopAtEmptyClouds

@@ -0,0 +1,20 @@
+/*--------------------------------*- C++ -*----------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     | Website:  https://openfoam.org
+    \\  /    A nd           | Version:  dev
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+Description
+    Stops the run when all clouds are empty (i.e., have no particles)
+
+\*---------------------------------------------------------------------------*/
+
+type            stopAtEmptyClouds;
+libs            ("liblagrangianFunctionObjects.so");
+
+action          nextWrite;
+
+executeControl  timeStep;
+
+// ************************************************************************* //

src/functionObjects/Allwmake

@@ -6,8 +6,8 @@ cd ${0%/*} || exit 1    # Run from this directory
 
 wmake $targetType field
 wmake $targetType forces
-wmake $targetType lagrangian
 wmake $targetType utilities
+wmake $targetType lagrangian
 wmake $targetType solvers
 
 #------------------------------------------------------------------------------

src/functionObjects/lagrangian/Make/files

@@ -1,5 +1,6 @@
 cloudInfo/cloudInfo.C
 dsmcFields/dsmcFields.C
 particles/particles.C
+stopAtEmptyClouds/stopAtEmptyClouds.C
 
 LIB = $(FOAM_LIBBIN)/liblagrangianFunctionObjects

src/functionObjects/lagrangian/Make/options

@@ -5,7 +5,8 @@ EXE_INC = \
     -I$(LIB_SRC)/lagrangian/basic/lnInclude \
     -I$(LIB_SRC)/lagrangian/parcel/lnInclude \
     -I$(LIB_SRC)/lagrangian/DSMC/lnInclude \
-    -I$(LIB_SRC)/surfaceFilmModels/lnInclude
+    -I$(LIB_SRC)/surfaceFilmModels/lnInclude \
+    -I$(LIB_SRC)/functionObjects/utilities/lnInclude
 
 LIB_LIBS = \
     -lfiniteVolume \
@@ -14,4 +15,5 @@ LIB_LIBS = \
     -llagrangian \
     -llagrangianParcel \
     -llagrangianParcelTurbulence \
-    -lsurfaceFilmModels
+    -lsurfaceFilmModels \
+    -lutilityFunctionObjects

src/functionObjects/lagrangian/stopAtEmptyClouds/stopAtEmptyClouds.C

@@ -0,0 +1,104 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     | Website:  https://openfoam.org
+    \\  /    A nd           | Copyright (C) 2022 OpenFOAM Foundation
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+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 "stopAtEmptyClouds.H"
+#include "parcelCloudList.H"
+#include "addToRunTimeSelectionTable.H"
+
+// * * * * * * * * * * * * * * Static Data Members * * * * * * * * * * * * * //
+
+namespace Foam
+{
+namespace functionObjects
+{
+    defineTypeNameAndDebug(stopAtEmptyClouds, 0);
+    addToRunTimeSelectionTable(functionObject, stopAtEmptyClouds, dictionary);
+}
+}
+
+
+// * * * * * * * * * * * * * Private Member Functions  * * * * * * * * * * * //
+
+bool Foam::functionObjects::stopAtEmptyClouds::condition() const
+{
+    // Potentially nothing has been injected yet. Wait for a step. If the
+    // clouds begin injection later than this, then time controls will be
+    // needed to delay the execution of this function.
+    if (time_.timeIndex() == time_.startTimeIndex())
+    {
+        return false;
+    }
+
+    // Loop all regions and all clouds in each region. If a non-empty cloud is
+    // found then do not stop.
+    bool noClouds = true;
+
+    const HashTable<const polyMesh*> meshes =
+        time_.lookupClass<polyMesh>();
+
+    forAllConstIter(HashTable<const polyMesh*>, meshes, meshIter)
+    {
+        const HashTable<const parcelCloud*> clouds =
+            meshIter()->lookupClass<parcelCloud>();
+
+        forAllConstIter(HashTable<const parcelCloud*>, clouds, cloudIter)
+        {
+            noClouds = false;
+
+            if (returnReduce(cloudIter()->nParcels(), sumOp<label>()) != 0)
+            {
+                return false;
+            }
+        }
+    }
+
+    // Either there are no clouds or there are clouds and all of them are
+    // empty. Stop if the latter.
+    return !noClouds;
+}
+
+
+// * * * * * * * * * * * * * * * * Constructors  * * * * * * * * * * * * * * //
+
+Foam::functionObjects::stopAtEmptyClouds::stopAtEmptyClouds
+(
+    const word& name,
+    const Time& runTime,
+    const dictionary& dict
+)
+:
+    stopAt(name, runTime, dict)
+{
+    read(dict);
+}
+
+
+// * * * * * * * * * * * * * * * * Destructor  * * * * * * * * * * * * * * * //
+
+Foam::functionObjects::stopAtEmptyClouds::~stopAtEmptyClouds()
+{}
+
+
+// ************************************************************************* //

src/functionObjects/lagrangian/stopAtEmptyClouds/stopAtEmptyClouds.H

@@ -0,0 +1,120 @@
+/*---------------------------------------------------------------------------*\
+  =========                 |
+  \\      /  F ield         | OpenFOAM: The Open Source CFD Toolbox
+   \\    /   O peration     | Website:  https://openfoam.org
+    \\  /    A nd           | Copyright (C) 2022 OpenFOAM Foundation
+     \\/     M anipulation  |
+-------------------------------------------------------------------------------
+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/>.
+
+Class
+    Foam::functionObjects::stopAtEmptyClouds
+
+Description
+    Stops the run when all parcel clouds are empty.
+
+    The following actions are supported:
+    - noWriteNow
+    - writeNow
+    - nextWrite (default)
+
+    Example of function object specification:
+    \verbatim
+    stop
+    {
+        type            stopAtEmptyClouds;
+        libs            ("liblagrangianFunctionObjects.so");
+
+        executeControl  timeStep; // <-- Likely only to be needed if injection
+        startTime       0.500001; // starts after time zero. In which case the
+                                  // startTime should be slightly after the
+                                  // injection start time.
+
+        action          nextWrite;
+    }
+    \endverbatim
+
+Usage
+    \table
+        Property | Description                  | Required | Default value
+        type     | type name: stopAtEmptyClouds | yes      |
+        action   | Action executed              | no       | nextWrite
+    \endtable
+
+SourceFiles
+    stopAtEmptyClouds.C
+
+\*---------------------------------------------------------------------------*/
+
+#ifndef stopAtEmptyClouds_H
+#define stopAtEmptyClouds_H
+
+#include "stopAt.H"
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+namespace Foam
+{
+namespace functionObjects
+{
+
+/*---------------------------------------------------------------------------*\
+                       Class stopAtEmptyClouds Declaration
+\*---------------------------------------------------------------------------*/
+
+class stopAtEmptyClouds
+:
+    public stopAt
+{
+    // Private Member Functions
+
+        //- Return true when the stop condition is achieved
+        virtual bool condition() const;
+
+
+public:
+
+    //- Runtime type information
+    TypeName("stopAtEmptyClouds");
+
+
+    // Constructors
+
+        //- Construct from Time and dictionary
+        stopAtEmptyClouds
+        (
+            const word& name,
+            const Time& runTime,
+            const dictionary& dict
+        );
+
+
+    //- Destructor
+    virtual ~stopAtEmptyClouds();
+};
+
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+} // End namespace functionObjects
+} // End namespace Foam
+
+// * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
+
+#endif
+
+// ************************************************************************* //