externalFileCoupler Class Reference

Encapsulates the logic for coordinating between OpenFOAM and an external application. More...

Inheritance diagram for externalFileCoupler:
[legend]
Collaboration diagram for externalFileCoupler:
[legend]

Public Types

enum  runState { NONE , MASTER , SLAVE , DONE }
 The run state (ie, who is currently in charge) More...
 

Public Member Functions

 TypeName ("externalFileCoupler")
 Runtime type information. More...
 
 externalFileCoupler ()
 Construct using standard defaults. More...
 
 externalFileCoupler (const fileName &commsDir)
 Construct with specified communications directory. More...
 
 externalFileCoupler (const dictionary &dict)
 Construct from dictionary. More...
 
virtual ~externalFileCoupler ()
 Destructor. More...
 
bool initialized () const
 True if state has been initialized. More...
 
bool slaveFirst () const
 External application provides initial values. More...
 
const fileNamecommDirectory () const
 Return the file path to the base communications directory. More...
 
fileName resolveFile (const word &file) const
 Return the file path in the communications directory. More...
 
fileName lockFile () const
 Return the file path to the lock file. More...
 
bool readDict (const dictionary &dict)
 Read communication settings from dictionary. More...
 
enum Time::stopAtControls useMaster (const bool wait=false) const
 Create lock file to indicate that OpenFOAM is in charge. More...
 
enum Time::stopAtControls useSlave (const bool wait=false) const
 Remove lock file to indicate that the external program is in charge. More...
 
enum Time::stopAtControls waitForMaster () const
 Wait for master to complete. More...
 
enum Time::stopAtControls waitForSlave () const
 Wait for slave to complete. More...
 
virtual void readDataMaster ()
 Read data files on master (OpenFOAM). More...
 
virtual void readDataSlave ()
 Read data files on slave (external program). More...
 
virtual void writeDataMaster () const
 Write data files from master (OpenFOAM) More...
 
virtual void writeDataSlave () const
 Write data files from slave (external program) More...
 
virtual void removeDataMaster () const
 Remove data files written by master (OpenFOAM) More...
 
virtual void removeDataSlave () const
 Remove data files written by slave (external program) More...
 
void shutdown () const
 Generate status=done in lock (only when run-state = master) More...
 
void removeDirectory () const
 Remove files written by OpenFOAM. More...
 

Static Public Attributes

static word lockName = "OpenFOAM"
 Name of the lock file. More...
 

Detailed Description

Encapsulates the logic for coordinating between OpenFOAM and an external application.

This class provides a simple interface for explicit coupling with an external application using plain text files located in the user-specified communications directory. These files are to be read/written on the master processor only.

The explicit coupling follows a master/slave model in which OpenFOAM is the 'master' and the external application is the 'slave'. The readiness to exchange information in either direction is handled by a lock file (ie, OpenFOAM.lock). If the lock file is present, the slave (external application) should wait for the master (OpenFOAM) to complete.

When the master is finished its tasks and has prepared data for the slave, the lock file is removed, instructing the external source to take control of the program execution.

When the slave has completed its tasks, it will reinstate the lock file.

Example of the communication specification:

communication
{
    commsDir        "<case>/comms";
    waitInterval    1;
    timeOut         100;
    initByExternal  no;
    statusDone      done;
}

A typical coupling loop would look like this (on the master-side):

    initialize - master takes control
    writeDataMaster() - write data for slave
    useSlave()
    waitForSlave()
    removeDataMaster() - cleanup old data from master [optional?]
    readDataMaster() - read data from slave
    useMaster()

On the slave-side:

    waitForMaster()
    readDataSlave()  - read data from master
    writeDataSlave() - write data for master
    useMaster()

Note that since the waitForSlave() method not only waits for the lock file to be reinstated but also does a simple check of its contents, it can also serve to communicate some control from the slave to the master.

Source files

Definition at line 107 of file externalFileCoupler.H.

Member Enumeration Documentation

◆ runState

enum runState

The run state (ie, who is currently in charge)

Enumerator
NONE 

Not initialized.

MASTER 

The master (OpenFOAM) is in charge.

SLAVE 

The slave (external program) is in charge.

DONE 

Finished.

Definition at line 114 of file externalFileCoupler.H.

Constructor & Destructor Documentation

◆ externalFileCoupler() [1/3]

Construct using standard defaults.

Does not create communications directory.

Definition at line 95 of file externalFileCoupler.C.

References fileName::clean(), string::expand(), and Foam::log().

Here is the call graph for this function:

◆ externalFileCoupler() [2/3]

externalFileCoupler ( const fileName commsDir)

Construct with specified communications directory.

Creates the communications directory upon construction.

Definition at line 110 of file externalFileCoupler.C.

References fileName::clean(), string::expand(), splitCell::master(), and Foam::mkDir().

Here is the call graph for this function:

◆ externalFileCoupler() [3/3]

externalFileCoupler ( const dictionary dict)

Construct from dictionary.

Creates the communications directory upon construction.

Definition at line 130 of file externalFileCoupler.C.

References dict, splitCell::master(), Foam::mkDir(), and externalFileCoupler::readDict().

Here is the call graph for this function:

◆ ~externalFileCoupler()

~externalFileCoupler ( )
virtual

Destructor.

Definition at line 145 of file externalFileCoupler.C.

Member Function Documentation

◆ TypeName()

TypeName ( "externalFileCoupler"  )

Runtime type information.

◆ initialized()

bool initialized ( ) const
inline

True if state has been initialized.

Definition at line 30 of file externalFileCouplerI.H.

References externalFileCoupler::NONE.

◆ slaveFirst()

bool slaveFirst ( ) const
inline

External application provides initial values.

Definition at line 36 of file externalFileCouplerI.H.

Referenced by externalCoupled::externalCoupled().

Here is the caller graph for this function:

◆ commDirectory()

const Foam::fileName & commDirectory ( ) const
inline

Return the file path to the base communications directory.

Definition at line 42 of file externalFileCouplerI.H.

◆ resolveFile()

Foam::fileName resolveFile ( const word file) const
inline

Return the file path in the communications directory.

Definition at line 48 of file externalFileCouplerI.H.

◆ lockFile()

Foam::fileName lockFile ( ) const
inline

Return the file path to the lock file.

Definition at line 57 of file externalFileCouplerI.H.

◆ readDict()

bool readDict ( const dictionary dict)

Read communication settings from dictionary.

Definition at line 153 of file externalFileCoupler.C.

References dict, Foam::endl(), dictionary::getOrDefault(), Foam::Info, Foam::log(), Foam::nl, externalFileCoupler::readDict(), dictionary::readEntry(), and Foam::type().

Referenced by externalFileCoupler::externalFileCoupler(), and externalFileCoupler::readDict().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ useMaster()

enum Foam::Time::stopAtControls useMaster ( const bool  wait = false) const

Create lock file to indicate that OpenFOAM is in charge.

Parameters
wait- wait for master to complete.
Returns
Time::stopAtControls::saUnknown if not waiting, otherwise as per the waitForMaster() description.

Definition at line 186 of file externalFileCoupler.C.

References Foam::endl(), Foam::isFile(), Log, splitCell::master(), Foam::mkDir(), os(), Time::saUnknown, and Foam::type().

Referenced by externalCoupled::externalCoupled().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ useSlave()

enum Foam::Time::stopAtControls useSlave ( const bool  wait = false) const

Remove lock file to indicate that the external program is in charge.

Parameters
wait- wait for slave to complete.
Returns
Time::stopAtControls::saUnknown if not waiting, otherwise as per the waitForSlave() description.

Definition at line 222 of file externalFileCoupler.C.

References Foam::endl(), Log, splitCell::master(), Foam::mkDir(), Foam::rm(), Time::saUnknown, and Foam::type().

Here is the call graph for this function:

◆ waitForMaster()

enum Foam::Time::stopAtControls waitForMaster ( ) const

Wait for master to complete.

This is when the lock file disappears, or exists but has status=done content.

Returns
Time::stopAtControls::saUnknown or if lock file contained status=done it returns Time::stopAtControls::saEndTime

Definition at line 250 of file externalFileCoupler.C.

References Foam::getStopAction(), Foam::highResLastModified(), splitCell::master(), Time::saEndTime, Time::saUnknown, Pstream::scatter(), and Foam::sleep().

Here is the call graph for this function:

◆ waitForSlave()

enum Foam::Time::stopAtControls waitForSlave ( ) const

Wait for slave to complete.

This is when the lock file appears.

When the lock file appears, it is checked for the following content which corresponds to particular return values:

Definition at line 294 of file externalFileCoupler.C.

References Foam::abort(), Foam::endl(), Foam::FatalError, FatalErrorInFunction, Foam::getStopAction(), Foam::isFile(), Log, splitCell::master(), Time::saUnknown, Pstream::scatter(), Foam::sleep(), and Foam::type().

Here is the call graph for this function:

◆ readDataMaster()

void readDataMaster ( )
virtual

Read data files on master (OpenFOAM).

These data files are normally created by the slave.

Reimplemented in externalCoupled.

Definition at line 337 of file externalFileCoupler.C.

◆ readDataSlave()

void readDataSlave ( )
virtual

Read data files on slave (external program).

These data files are normally created by the master.

Definition at line 341 of file externalFileCoupler.C.

◆ writeDataMaster()

void writeDataMaster ( ) const
virtual

Write data files from master (OpenFOAM)

Reimplemented in externalCoupled.

Definition at line 345 of file externalFileCoupler.C.

◆ writeDataSlave()

void writeDataSlave ( ) const
virtual

Write data files from slave (external program)

Definition at line 349 of file externalFileCoupler.C.

◆ removeDataMaster()

void removeDataMaster ( ) const
virtual

Remove data files written by master (OpenFOAM)

Reimplemented in externalCoupled.

Definition at line 353 of file externalFileCoupler.C.

◆ removeDataSlave()

void removeDataSlave ( ) const
virtual

Remove data files written by slave (external program)

Reimplemented in externalCoupled.

Definition at line 357 of file externalFileCoupler.C.

◆ shutdown()

void shutdown ( ) const

Generate status=done in lock (only when run-state = master)

The exact text can be specified via the statusDone keyword

Definition at line 361 of file externalFileCoupler.C.

References Foam::endl(), Foam::isDir(), Log, splitCell::master(), Foam::nl, os(), and Foam::type().

Referenced by ParRunControl::~ParRunControl().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ removeDirectory()

void removeDirectory ( ) const

Remove files written by OpenFOAM.

Member Data Documentation

◆ lockName

Foam::word lockName = "OpenFOAM"
static

Name of the lock file.

Definition at line 166 of file externalFileCoupler.H.


The documentation for this class was generated from the following files: