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")

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

	externalCoupled (const externalCoupled &)=delete

void	operator= (const externalCoupled &)=delete

virtual	~externalCoupled ()=default

virtual bool	execute ()

virtual bool	execute (const label subIndex)

virtual bool	end ()

virtual bool	read (const dictionary &dict)

virtual bool	write ()

virtual void	writeDataMaster () const

virtual void	readDataMaster ()

virtual void	removeDataMaster () const

virtual void	removeDataSlave () const

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)

virtual	~timeFunctionObject ()=default

const Time &	time () const

objectRegistry &	storedObjects ()

const objectRegistry &	storedObjects () const

Public Member Functions inherited from functionObject
	declareRunTimeSelectionTable (autoPtr, functionObject, dictionary,(const word &name, const Time &runTime, const dictionary &dict),(name, runTime, dict))

	functionObject (const word &name, const bool withNamePrefix=defaultUseNamePrefix)

autoPtr< functionObject >	clone () const

virtual	~functionObject ()=default

virtual const word &	type () const =0

const word &	name () const noexcept

bool	useNamePrefix () const noexcept

bool	useNamePrefix (bool on) noexcept

virtual bool	adjustTimeStep ()

virtual bool	filesModified () const

virtual void	updateMesh (const mapPolyMesh &mpm)

virtual void	movePoints (const polyMesh &mesh)

Public Member Functions inherited from externalFileCoupler
	TypeName ("externalFileCoupler")

	externalFileCoupler ()

	externalFileCoupler (const fileName &commsDir)

	externalFileCoupler (const dictionary &dict)

virtual	~externalFileCoupler ()

bool	initialized () const

bool	slaveFirst () const

const fileName &	commDirectory () const

fileName	resolveFile (const word &file) const

fileName	lockFile () const

bool	readDict (const dictionary &dict)

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

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

enum Time::stopAtControls	waitForMaster () const

enum Time::stopAtControls	waitForSlave () const

virtual void	readDataSlave ()

virtual void	writeDataSlave () const

void	shutdown () const

void	removeDirectory () const

Static Public Member Functions
static word	compositeName (const wordList &)

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

Static Public Member Functions inherited from functionObject
static autoPtr< functionObject >	New (const word &name, const Time &runTime, const dictionary &dict)

Public Attributes
bool	log

Public Attributes inherited from functionObject
bool	log

Static Public Attributes
static string	patchKey = "// Patch:"

Static Public Attributes inherited from functionObject
static int	debug

static bool	postProcess

static bool	defaultUseNamePrefix

static word	outputPrefix

Static Public Attributes inherited from externalFileCoupler
static word	lockName = "OpenFOAM"

Additional Inherited Members
Public Types inherited from externalFileCoupler
enum	runState { NONE, MASTER, SLAVE, DONE }

Protected Member Functions inherited from timeFunctionObject
void	clearOutputObjects (const wordList &objNames)

	timeFunctionObject (const timeFunctionObject &)=delete

void	operator= (const timeFunctionObject &)=delete

Protected Member Functions inherited from functionObject
word	scopedName (const word &name) const

Protected Attributes inherited from timeFunctionObject
const Time &	time_

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