externalCoupled Class Reference

Provides a simple file-based communication interface for explicit coupling with an external application, so that data is transferred to- and from OpenFOAM. The data exchange employs specialised boundary conditions to provide either one-way or two-way coupling models. More...

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

Public Member Functions

 TypeName ("externalCoupled")
 Runtime type information. More...
 
 externalCoupled (const word &name, const Time &runTime, const dictionary &dict)
 Construct given time and dictionary. More...
 
 externalCoupled (const externalCoupled &)=delete
 No copy construct. More...
 
void operator= (const externalCoupled &)=delete
 No copy assignment. More...
 
virtual ~externalCoupled ()=default
 Destructor. More...
 
virtual bool execute ()
 Called at each ++ or += of the time-loop. More...
 
virtual bool execute (const label subIndex)
 Manual execute (sub-loop or when converged) More...
 
virtual bool end ()
 Called when Time::run() determines that the time-loop exits. More...
 
virtual bool read (const dictionary &dict)
 Read and set the function object if its data have changed. More...
 
virtual bool write ()
 Write, currently a no-op. More...
 
virtual void writeDataMaster () const
 Write data files (all regions, all fields) from master (OpenFOAM) More...
 
virtual void readDataMaster ()
 Read data files (all regions, all fields) on master (OpenFOAM) More...
 
virtual void removeDataMaster () const
 Remove data files written by master (OpenFOAM) More...
 
virtual void removeDataSlave () const
 Remove data files written by slave (external code) More...
 
template<class Type >
Foam::tmp< Foam::Field< Type > > gatherAndCombine (const Field< Type > &fld)
 
- Public Member Functions inherited from timeFunctionObject
 timeFunctionObject (const word &name, const Time &runTime)
 Construct from Time. More...
 
virtual ~timeFunctionObject ()=default
 Destructor. More...
 
const Timetime () const
 Return time database. More...
 
objectRegistrystoredObjects ()
 
const objectRegistrystoredObjects () const
 
- Public Member Functions inherited from functionObject
virtual const wordtype () const =0
 Runtime type information. More...
 
 declareRunTimeSelectionTable (autoPtr, functionObject, dictionary,(const word &name, const Time &runTime, const dictionary &dict),(name, runTime, dict))
 
 functionObject (const word &name)
 Construct from components. More...
 
autoPtr< functionObjectclone () const
 Return clone. More...
 
virtual ~functionObject ()=default
 Destructor. More...
 
const wordname () const
 Return the name of this functionObject. More...
 
virtual bool adjustTimeStep ()
 Called at the end of Time::adjustDeltaT() if adjustTime is true. More...
 
virtual bool filesModified () const
 Did any file get changed during execution? More...
 
virtual void updateMesh (const mapPolyMesh &mpm)
 Update for changes of mesh. More...
 
virtual void movePoints (const polyMesh &mesh)
 Update for changes of mesh. More...
 
- Public Member Functions inherited from externalFileCoupler
 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 readDataSlave ()
 Read data files on slave (external program). More...
 
virtual void writeDataSlave () const
 Write data files from 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 Member Functions

static word compositeName (const wordList &)
 
static void writeGeometry (const UPtrList< const fvMesh > &meshes, const fileName &commsDir, const wordRe &groupName)
 Write geometry for the group as region/patch. More...
 
- Static Public Member Functions inherited from functionObject
static autoPtr< functionObjectNew (const word &name, const Time &runTime, const dictionary &dict)
 Select from dictionary, based on its "type" entry. More...
 

Public Attributes

bool log
 Inherited variable for logging. More...
 
- Public Attributes inherited from functionObject
bool log
 Flag to write log into Info. More...
 

Static Public Attributes

static string patchKey = "// Patch:"
 Name of patch key, e.g. '// Patch:' when looking for start of patch data. More...
 
- Static Public Attributes inherited from functionObject
static int debug
 Flag to execute debug content. More...
 
static bool postProcess
 Global post-processing mode switch. More...
 
static word outputPrefix
 Directory prefix. More...
 
- Static Public Attributes inherited from externalFileCoupler
static word lockName = "OpenFOAM"
 Name of the lock file. More...
 

Additional Inherited Members

- Public Types inherited from externalFileCoupler
enum  runState { NONE, MASTER, SLAVE, DONE }
 The run state (ie, who is currently in charge) More...
 
- Protected Member Functions inherited from timeFunctionObject
void clearOutputObjects (const wordList &objNames)
 Remove specified items from "functionObjectObjects". More...
 
 timeFunctionObject (const timeFunctionObject &)=delete
 No copy construct. More...
 
void operator= (const timeFunctionObject &)=delete
 No copy assignment. More...
 
- Protected Member Functions inherited from functionObject
word scopedName (const word &name) const
 Return a scoped name, e.g. used to construct local field names. More...
 
- Protected Attributes inherited from timeFunctionObject
const Timetime_
 Reference to the time database. More...
 

Detailed Description

Provides a simple file-based communication interface for explicit coupling with an external application, so that data is transferred to- and from OpenFOAM. The data exchange employs specialised boundary conditions to provide either one-way or two-way coupling models.

The coupling is through plain text files where OpenFOAM boundary data is read/written as one line per face (data from all processors collated):

    # Patch: <patch name>
    <fld1> <fld2> .. <fldn>             //face0
    <fld1> <fld2> .. <fldn>             //face1
    ..
    <fld1> <fld2> .. <fldn>             //faceN

where the actual entries depend on the boundary condition type:

  • mixed: value, snGrad, refValue, refGrad, valueFraction
  • externalCoupledMixed: output of writeDataMaster
  • other: value, snGrad

These text files are located in a user specified communications directory which gets read/written on the master processor only.

In the communications directory the structure will be:

    <regionsName>/<patchGroup>/<fieldName>.[in|out]

(where regionsName is either the name of a single region or a composite of multiple region names)

At start-up, the boundary creates a lock file, i.e.:

    OpenFOAM.lock

... to signal the external source to wait. During the function object execution the boundary values are written to files (one per region, per patch(group), per field), e.g.

    <regionsName>/<patchGroup>/<fieldName>.out

The lock file is then removed, instructing the external source to take control of the program execution. When ready, the external program should create the return values, e.g. to files

    <regionsName>/<patchGroup>/<fieldName>.in

... and then reinstate the lock file. The function object will then read these values, apply them to the boundary conditions and pass program execution back to OpenFOAM.

Usage
Minimal example by using system/controlDict.functions:
externalCoupled1
{
    // Mandatory entries (unmodifiable)
    type            externalCoupled;
    libs            (fieldFunctionObjects);
    commsDir        "<case>/comms";
    regions
    {
        "(region1|region0)"         // Name of region(s)
        {
            TPatchGroup             // Name of patch(group)
            {
                readFields  (p);    // List of fields to read
                writeFields (T);    // List of fields to write
            }
        }
    }
    initByExternal  true;

    // Optional entries (runtime modifiable)
    waitInterval    1;
    timeOut         100;
    statusDone      done;  // Any arbitrary status=... value
    calcFrequency   1;

    // Optional (inherited) entries
    ...
}

This reads/writes (on the master processor) the directory:

    comms/region0_region1/TPatchGroup/

with contents:

    patchPoints     (collected points)
    patchFaces      (collected faces)
    p.in            (input file of p, written by external application)
    T.out           (output file of T, written by OpenFOAM)

The patchPoints/patchFaces files denote the (collated) geometry which will be written if it does not exist yet or can be written as a preprocessing step using the createExternalCoupledPatchGeometry application.

The entries comprise:

Property Description Type Req'd Dflt
type Type name: externalCoupled word yes -
libs Library name: fieldFunctionObjects word yes -
commsDir Communication directory word yes -
regions The regions to couple word yes -
initByExternal Initialization values supplied by external app bool yes -
waitInterval Wait interval in [s] label no 1
timeOut Timeout in [s] label no 100*waitInterval
statusDone Lockfile status=... on termination word no done
calcFrequency Calculation frequency label no 1

The inherited entries are elaborated in:

Usage by the postProcess utility is not available.

See also
Source files

Definition at line 257 of file externalCoupled.H.

Constructor & Destructor Documentation

◆ externalCoupled() [1/2]

externalCoupled ( const word name,
const Time runTime,
const dictionary dict 
)

Construct given time and dictionary.

Definition at line 500 of file externalCoupled.C.

References dict, and Foam::read().

Here is the call graph for this function:

◆ externalCoupled() [2/2]

externalCoupled ( const externalCoupled )
delete

No copy construct.

◆ ~externalCoupled()

virtual ~externalCoupled ( )
virtualdefault

Destructor.

Member Function Documentation

◆ TypeName()

TypeName ( "externalCoupled"  )

Runtime type information.

◆ operator=()

void operator= ( const externalCoupled )
delete

No copy assignment.

◆ execute() [1/2]

bool execute ( )
virtual

Called at each ++ or += of the time-loop.

Implements functionObject.

Definition at line 523 of file externalCoupled.C.

◆ execute() [2/2]

bool execute ( const label  subIndex)
virtual

Manual execute (sub-loop or when converged)

Reimplemented from functionObject.

Definition at line 539 of file externalCoupled.C.

◆ end()

bool end ( )
virtual

Called when Time::run() determines that the time-loop exits.

Reimplemented from functionObject.

Definition at line 547 of file externalCoupled.C.

References functionObject::end().

Here is the call graph for this function:

◆ read()

bool read ( const dictionary dict)
virtual

Read and set the function object if its data have changed.

Reimplemented from functionObject.

Definition at line 560 of file externalCoupled.C.

References Foam::decrIndent(), dict, Foam::endl(), Foam::exit(), Foam::FatalIOError, FatalIOErrorInFunction, Foam::findStrings(), MinMax< T >::ge(), Foam::incrIndent(), Foam::indent(), Foam::Info, Foam::isDir(), Log, UPstream::master(), Foam::mkDir(), Foam::nl, functionObject::read(), externalFileCoupler::readDict(), Foam::readFields(), HashTable< T, Key, Hash >::sortedToc(), Foam::type(), and Foam::writeFields().

Here is the call graph for this function:

◆ write()

bool write ( )
virtual

Write, currently a no-op.

Implements functionObject.

Definition at line 829 of file externalCoupled.C.

◆ writeDataMaster()

void writeDataMaster ( ) const
virtual

Write data files (all regions, all fields) from master (OpenFOAM)

Reimplemented from externalFileCoupler.

Definition at line 725 of file externalCoupled.C.

References Foam::endl(), forAll, meshes(), and WarningInFunction.

Here is the call graph for this function:

◆ readDataMaster()

void readDataMaster ( )
virtual

Read data files (all regions, all fields) on master (OpenFOAM)

Reimplemented from externalFileCoupler.

Definition at line 681 of file externalCoupled.C.

References Foam::endl(), forAll, meshes(), and WarningInFunction.

Here is the call graph for this function:

◆ removeDataMaster()

void removeDataMaster ( ) const
virtual

Remove data files written by master (OpenFOAM)

Reimplemented from externalFileCoupler.

Definition at line 769 of file externalCoupled.C.

References Log, UPstream::master(), Foam::nl, Foam::rm(), and Foam::type().

Here is the call graph for this function:

◆ removeDataSlave()

void removeDataSlave ( ) const
virtual

Remove data files written by slave (external code)

Reimplemented from externalFileCoupler.

Definition at line 799 of file externalCoupled.C.

References Log, UPstream::master(), Foam::nl, Foam::rm(), and Foam::type().

Here is the call graph for this function:

◆ compositeName()

Foam::word compositeName ( const wordList regionNames)
static

Create single name by appending words (in sorted order), separated by '_'

Definition at line 345 of file externalCoupled.C.

References Foam::abort(), polyMesh::defaultRegion, Foam::FatalError, FatalErrorInFunction, and word::null.

Here is the call graph for this function:

◆ writeGeometry()

void writeGeometry ( const UPtrList< const fvMesh > &  meshes,
const fileName commsDir,
const wordRe groupName 
)
static

Write geometry for the group as region/patch.

Definition at line 237 of file externalCoupled.C.

References Foam::DelaunayMeshTools::allPoints(), DynamicList< T, SizeMin >::append(), DynamicList< T, SizeMin >::clear(), Foam::endl(), forAll, Pstream::gatherList(), Foam::Info, Foam::inplaceRenumber(), UPstream::master(), mesh, meshes(), Foam::mkDir(), UPstream::myProcNo(), Foam::nl, UPstream::nProcs(), p, autoPtr< T >::reset(), and Foam::vtk::writeList().

Here is the call graph for this function:

◆ gatherAndCombine()

Foam::tmp<Foam::Field<Type> > gatherAndCombine ( const Field< Type > &  fld)

Definition at line 271 of file externalCoupledTemplates.C.

References fld, forAll, Pstream::gatherList(), UPstream::master(), UPstream::myProcNo(), Foam::New(), UPstream::nProcs(), and List< T >::setSize().

Here is the call graph for this function:

Member Data Documentation

◆ patchKey

Foam::string patchKey = "// Patch:"
static

Name of patch key, e.g. '// Patch:' when looking for start of patch data.

Definition at line 362 of file externalCoupled.H.

◆ log

Inherited variable for logging.

Definition at line 343 of file functionObject.H.


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