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 Time &	time () const
	Return time database. More...

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)
	Construct from components. More...

autoPtr< functionObject >	clone () const
	Return clone. More...

virtual	~functionObject ()=default
	Destructor. More...

virtual const word &	type () const =0
	Runtime type information. More...

const word &	name () const noexcept
	Return the name of this functionObject. More...

bool	useNamePrefix () const noexcept
	Return the flag for adding a scoping name prefix. More...

bool	useNamePrefix (bool on) noexcept
	Modify the flag for adding a scoping name prefix. More...

virtual bool	read (const dictionary &dict)
	Read and set the function object if its data have changed. More...

virtual bool	execute ()=0
	Called at each ++ or += of the time-loop. More...

virtual bool	execute (const label subIndex)
	Execute using the specified subIndex. More...

virtual bool	write ()=0
	Called at each ++ or += of the time-loop. More...

virtual bool	end ()
	Called when Time::run() determines that the time-loop exits. 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 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 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< functionObject >	New (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 bool	defaultUseNamePrefix
	Global default for useNamePrefix. 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 (prefixed) name. More...

Protected Attributes inherited from timeFunctionObject
const Time &	time_
	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:

timeFunctionObject.H

Usage by the postProcess utility is not available.

See also

Foam::functionObject
Foam::functionObjects::timeFunctionObject
Foam::externalFileCouple
ExtendedCodeGuide::functionObjects::field::externalCoupled

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 499 of file externalCoupled.C.

References dict, externalCoupled::read(), externalFileCoupler::slaveFirst(), and externalFileCoupler::useMaster().

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(), dictionary::get(), Foam::incrIndent(), Foam::indent(), Foam::Info, Foam::isDir(), Log, splitCell::master(), Foam::mkDir(), Foam::nl, kEpsilonLopesdaCosta< BasicTurbulenceModel >::read(), regionNames, HashTable< T, Key, Hash >::sortedToc(), Foam::type(), and Foam::writeFields().

Referenced by externalCoupled::externalCoupled().

Here is the call graph for this function:

Here is the caller 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(), regionNames, PtrList< T >::set(), 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(), regionNames, PtrList< T >::set(), 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, splitCell::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, splitCell::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 344 of file externalCoupled.C.

References polyMesh::defaultRegion, Foam::FatalError, FatalErrorInFunction, word::null, and regionNames.

◆ 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 236 of file externalCoupled.C.

References PstreamBuffers::allProcs(), DynamicList< T, SizeMin >::append(), DynamicList< T, SizeMin >::clear(), Foam::endl(), forAll, Pstream::gatherList(), Foam::Info, Foam::inplaceRenumber(), splitCell::master(), mesh, meshes(), Foam::mkDir(), processorFaPatch::myProcNo(), Foam::nl, PstreamBuffers::nProcs(), p, regionNames, autoPtr< T >::reset(), UPtrList< T >::size(), and UList< T >::size().

Here is the call graph for this function:

◆ gatherAndCombine()

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

Definition at line 270 of file externalCoupledTemplates.C.

References fld(), forAll, Pstream::gatherList(), splitCell::master(), processorFaPatch::myProcNo(), Foam::New(), PstreamBuffers::nProcs(), and UList< T >::size().

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

bool log

Inherited variable for logging.

Definition at line 361 of file functionObject.H.

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

src/functionObjects/field/externalCoupled/externalCoupled.H
src/functionObjects/field/externalCoupled/externalCoupled.C
src/functionObjects/field/externalCoupled/externalCoupledTemplates.C

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ externalCoupled() [1/2]

◆ externalCoupled() [2/2]

◆ ~externalCoupled()

Member Function Documentation

◆ TypeName()

◆ operator=()

◆ execute() [1/2]

◆ execute() [2/2]

◆ end()

◆ read()

◆ write()

◆ writeDataMaster()

◆ readDataMaster()

◆ removeDataMaster()

◆ removeDataSlave()

◆ compositeName()

◆ writeGeometry()

◆ gatherAndCombine()

Member Data Documentation

◆ patchKey

◆ log