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

#include <externalFileCoupler.H>

Inheritance diagram for externalFileCoupler:

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

Static Public Attributes
static word	lockName = "OpenFOAM"
	Name of the lock file.

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 103 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 112 of file externalFileCoupler.H.

Constructor & Destructor Documentation

◆ externalFileCoupler() [1/3]

externalFileCoupler ( )

Construct using standard defaults.

Does not create communications directory.

Definition at line 88 of file externalFileCoupler.C.

References NONE.

◆ externalFileCoupler() [2/3]

externalFileCoupler ( const fileName & commsDir )

Construct with specified communications directory.

Creates the communications directory upon construction.

Definition at line 103 of file externalFileCoupler.C.

References UPstream::master(), Foam::mkDir(), and NONE.

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 123 of file externalFileCoupler.C.

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

Here is the call graph for this function:

◆ ~externalFileCoupler()

~externalFileCoupler ( )

virtual

Destructor.

Definition at line 138 of file externalFileCoupler.C.

References shutdown().

Here is the call graph for this function:

Member Function Documentation

◆ TypeName()

TypeName ( "externalFileCoupler" )

Runtime type information.

◆ initialized()

bool initialized ( ) const

inline

True if state has been initialized.

Definition at line 23 of file externalFileCouplerI.H.

References NONE.

Referenced by readDict(), useMaster(), useSlave(), waitForMaster(), and waitForSlave().

Here is the caller graph for this function:

◆ slaveFirst()

bool slaveFirst ( ) const

inline

External application provides initial values.

Definition at line 29 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 35 of file externalFileCouplerI.H.

Referenced by externalCoupled::read(), externalCoupled::removeDataMaster(), externalCoupled::removeDataSlave(), and resolveFile().

Here is the caller graph for this function:

◆ resolveFile()

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

inline

Return the file path in the communications directory.

Definition at line 41 of file externalFileCouplerI.H.

References commDirectory().

Referenced by lockFile().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ lockFile()

Foam::fileName lockFile ( ) const

inline

Return the file path to the lock file.

Definition at line 50 of file externalFileCouplerI.H.

References lockName, and resolveFile().

Referenced by shutdown(), useMaster(), useSlave(), waitForMaster(), and waitForSlave().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ readDict()

bool readDict ( const dictionary & dict )

Read communication settings from dictionary.

Definition at line 146 of file externalFileCoupler.C.

References dict, Foam::endl(), Foam::Info, initialized(), Foam::nl, and Foam::type().

Referenced by externalFileCoupler(), and externalCoupled::read().

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 179 of file externalFileCoupler.C.

References Foam::endl(), initialized(), Foam::isFile(), lockFile(), Log, MASTER, UPstream::master(), Foam::mkDir(), os(), Time::saUnknown, Foam::type(), and waitForMaster().

Referenced by externalCoupled::externalCoupled(), and waitForMaster().

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 215 of file externalFileCoupler.C.

References Foam::endl(), initialized(), lockFile(), Log, UPstream::master(), Foam::mkDir(), Foam::rm(), Time::saUnknown, SLAVE, Foam::type(), and waitForSlave().

Referenced by waitForSlave().

Here is the call graph for this function:

Here is the caller 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 243 of file externalFileCoupler.C.

References UPstream::broadcast, Foam::getStopAction(), Foam::highResLastModified(), initialized(), lockFile(), UPstream::master(), Time::saEndTime, Time::saUnknown, Foam::sleep(), and useMaster().

Referenced by useMaster().

Here is the call graph for this function:

Here is the caller 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:

status=done
Returns
Foam::Time::saEndTime
action=noWriteNow
Returns
Foam::Time::saNoWriteNow
action=writeNow
Returns
Foam::Time::saWriteNow
action=nextWrite
Returns
Foam::Time::saNextWrite
Anything else (empty file, no action= or status=, etc)
Returns
Foam::Time::saUnknown

Definition at line 287 of file externalFileCoupler.C.

References Foam::abort(), UPstream::broadcast, Foam::endl(), Foam::FatalError, FatalErrorInFunction, Foam::getStopAction(), initialized(), Foam::isFile(), lockFile(), Log, UPstream::master(), Time::saUnknown, Foam::sleep(), Foam::type(), and useSlave().

Referenced by useSlave().

Here is the call graph for this function:

Here is the caller 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 330 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 334 of file externalFileCoupler.C.

◆ writeDataMaster()

void writeDataMaster ( ) const

virtual

Write data files from master (OpenFOAM).

Reimplemented in externalCoupled.

Definition at line 338 of file externalFileCoupler.C.

◆ writeDataSlave()

void writeDataSlave ( ) const

virtual

Write data files from slave (external program).

Definition at line 342 of file externalFileCoupler.C.

◆ removeDataMaster()

void removeDataMaster ( ) const

virtual

Remove data files written by master (OpenFOAM).

Reimplemented in externalCoupled.

Definition at line 346 of file externalFileCoupler.C.

◆ removeDataSlave()

void removeDataSlave ( ) const

virtual

Remove data files written by slave (external program).

Reimplemented in externalCoupled.

Definition at line 350 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 354 of file externalFileCoupler.C.

References DONE, Foam::endl(), Foam::isDir(), lockFile(), Log, MASTER, UPstream::master(), Foam::nl, os(), and Foam::type().

Referenced by externalCoupled::end(), and ~externalFileCoupler().

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 186 of file externalFileCoupler.H.

Referenced by lockFile().

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

src/meshTools/coupling/externalFileCoupler.H
src/meshTools/coupling/externalFileCoupler.C
src/meshTools/coupling/externalFileCouplerI.H

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ runState

Constructor & Destructor Documentation

◆ externalFileCoupler() [1/3]

◆ externalFileCoupler() [2/3]

◆ externalFileCoupler() [3/3]

◆ ~externalFileCoupler()

Member Function Documentation

◆ TypeName()

◆ initialized()

◆ slaveFirst()

◆ commDirectory()

◆ resolveFile()

◆ lockFile()

◆ readDict()

◆ useMaster()

◆ useSlave()

◆ waitForMaster()

◆ waitForSlave()

◆ readDataMaster()

◆ readDataSlave()

◆ writeDataMaster()

◆ writeDataSlave()

◆ removeDataMaster()

◆ removeDataSlave()

◆ shutdown()

◆ removeDirectory()

Member Data Documentation

◆ lockName