Tip Function Object jobControl

1 Introduction to jobControl

The Function Object jobControl gives the user the power to control job execution, namely the solver associated with the currently executing case. This function object library has the following types:

• abort: Provides control over the stopping point of the solver. Valid versions:

What's this Function Object good for?

• Easier control over running solvers/cases.
• The control can come from an outside program or script.

2 Usage Description

A Function Object is a library that is included by defining in the system/controlDict file in the simulation case folder, how to load it and how to use it. For jobControl this is the base structure:

functions
{
    controlMyRun
    {
        type abort;
        functionObjectLibs ( "libjobControl.so" );
        action nextWrite;
        fileName "myname.flag";
    }
}

Description of details:

• controlMyRun is just the name given for this function on the functions list and it could be any other name.
• The type abort is a must, since its what defines which type this function object is going to use.
• functionObjectLibs defines in which library the desired function object is in.
• action can have one of three internal name values:
  • nextWrite for terminating after the next scheduled write is complete;
  • noWriteNow simply terminate now, or as soon as possible;
  • writeNow will issue a write command when the current time iteration (or similar) is complete.
• fileName indicates the file name to look for. It looks for it in the base folder of the case, if a full path is not given. Warning: do not give it a file name of an already existing file as it will kill it as soon as the application starts!

3 Example

Lets try this with the tutorial incompressible/icoFoam/cavity. Copy that folder to a safe place for doing this example.

Now, add this near the end of the system/controlDict file:

functions
{
    controlOnNext
    {
        type abort;
        functionObjectLibs ( "libjobControl.so" );
        action nextWrite;
        fileName "snapshot";
    }
 
    killNow
    {
        type abort;
        functionObjectLibs ( "libjobControl.so" );
        action noWriteNow;
        fileName "killrun";
    }
 
    suspendNow
    {
        type abort;
        functionObjectLibs ( "libjobControl.so" );
        action writeNow;
        fileName "suspend";
    }
}

There are three instances here because we want to be able to control the 3 scenarios!
Edit the entry startFrom on this same file and change startTime to latestTime.

Now run:

blockMesh
refineMesh -overwrite
refineMesh -overwrite
refineMesh -overwrite
icoFoam

Yes, run refineMesh 3 or 4 times, since this will make the mesh very refined and the case will be very slow as well, which is real nice for us to test the controls.

The last command launched icoFoam and you won't be able to execute commands here for now. Start a new terminal window or tab and go to the same folder where icoFoam is running. Lets test stopping icoFoam with writing as soon as possible; for this, run:

touch suspend

It will create and empty file with that name. Now go to the window or tab where icoFoam is running and It'll take a little while for it to stop. When it's over, you can see the the latest written folder by running:

ls -l

Also notice that the suspend file is no longer there!

OK, run icoFoam again. It should start from where it stopped. Now lets try making it stop without writing; for this run on the other terminal:

touch killrun

Go back to the other terminal and you'll see that as soon as it is over, there aren't any new time folders for the latest time being solved by icoFoam.

Last but not least, run icoFoam again. It should start from where it stopped on the other run. Now lets try making it stop on the next scheduled write time, which should be at 0.1s; for this run on the other terminal:

touch snapshot

Go back to the other terminal and wait a while... when it's over, you'll see the next scheduled write time to be well saved!

Now a special note about this case: it's very likely that this case will not solve and it will crash, since no other parameters were adapted for the high resolution mesh!