Encapsulates the logic for coordinating between OpenFOAM and an external application. More...
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 fileName & | commDirectory () 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... | |
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.
Definition at line 103 of file externalFileCoupler.H.
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.
Construct using standard defaults.
Does not create communications directory.
Definition at line 88 of file externalFileCoupler.C.
References fileName::clean(), and string::expand().
externalFileCoupler | ( | const fileName & | commsDir | ) |
Construct with specified communications directory.
Creates the communications directory upon construction.
Definition at line 103 of file externalFileCoupler.C.
References fileName::clean(), string::expand(), UPstream::master(), and Foam::mkDir().
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 externalFileCoupler::readDict().
|
virtual |
Destructor.
Definition at line 138 of file externalFileCoupler.C.
TypeName | ( | "externalFileCoupler" | ) |
Runtime type information.
|
inline |
True if state has been initialized.
Definition at line 23 of file externalFileCouplerI.H.
References externalFileCoupler::NONE.
|
inline |
External application provides initial values.
Definition at line 29 of file externalFileCouplerI.H.
|
inline |
Return the file path to the base communications directory.
Definition at line 35 of file externalFileCouplerI.H.
|
inline |
Return the file path in the communications directory.
Definition at line 42 of file externalFileCouplerI.H.
|
inline |
Return the file path to the lock file.
Definition at line 50 of file externalFileCouplerI.H.
bool readDict | ( | const dictionary & | dict | ) |
Read communication settings from dictionary.
Definition at line 146 of file externalFileCoupler.C.
References dict, Foam::endl(), dictionary::getOrDefault(), Foam::Info, Foam::log(), Foam::nl, dictionary::readEntry(), and Foam::type().
Referenced by externalFileCoupler::externalFileCoupler(), and externalCoupled::read().
enum Foam::Time::stopAtControls useMaster | ( | const bool | wait = false | ) | const |
Create lock file to indicate that OpenFOAM is in charge.
wait | - wait for master to complete. |
Definition at line 179 of file externalFileCoupler.C.
References Foam::endl(), Foam::isFile(), Log, UPstream::master(), Foam::mkDir(), os(), and Foam::type().
enum Foam::Time::stopAtControls useSlave | ( | const bool | wait = false | ) | const |
Remove lock file to indicate that the external program is in charge.
wait | - wait for slave to complete. |
Definition at line 215 of file externalFileCoupler.C.
References Foam::endl(), Log, UPstream::master(), Foam::mkDir(), Foam::rm(), and Foam::type().
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.
status=done
it returns Time::stopAtControls::saEndTime Definition at line 243 of file externalFileCoupler.C.
References Pstream::broadcast(), Foam::getStopAction(), Foam::highResLastModified(), UPstream::master(), and Foam::sleep().
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
action=noWriteNow
action=writeNow
action=nextWrite
Definition at line 287 of file externalFileCoupler.C.
References Foam::abort(), Pstream::broadcast(), Foam::endl(), Foam::FatalError, FatalErrorInFunction, Foam::getStopAction(), Foam::isFile(), Log, UPstream::master(), Foam::sleep(), and Foam::type().
|
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.
|
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.
|
virtual |
Write data files from master (OpenFOAM)
Reimplemented in externalCoupled.
Definition at line 338 of file externalFileCoupler.C.
|
virtual |
Write data files from slave (external program)
Definition at line 342 of file externalFileCoupler.C.
|
virtual |
Remove data files written by master (OpenFOAM)
Reimplemented in externalCoupled.
Definition at line 346 of file externalFileCoupler.C.
|
virtual |
Remove data files written by slave (external program)
Reimplemented in externalCoupled.
Definition at line 350 of file externalFileCoupler.C.
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 Foam::endl(), Foam::isDir(), Log, UPstream::master(), Foam::nl, os(), and Foam::type().
void removeDirectory | ( | ) | const |
Remove files written by OpenFOAM.
|
static |
Name of the lock file.
Definition at line 186 of file externalFileCoupler.H.