externalCoupledMixedFvPatchField.H
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*\
2  ========= |
3  \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4  \\ / O peration | Website: https://openfoam.org
5  \\ / A nd | Copyright (C) 2013-2023 OpenFOAM Foundation
6  \\/ M anipulation |
7 -------------------------------------------------------------------------------
8 License
9  This file is part of OpenFOAM.
10 
11  OpenFOAM is free software: you can redistribute it and/or modify it
12  under the terms of the GNU General Public License as published by
13  the Free Software Foundation, either version 3 of the License, or
14  (at your option) any later version.
15 
16  OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
17  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
18  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
19  for more details.
20 
21  You should have received a copy of the GNU General Public License
22  along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
23 
24 Class
25  Foam::externalCoupledMixedFvPatchField
26 
27 Description
28  This boundary condition provides an interface to an external application.
29  Values are transferred as plain text files, where OpenFOAM data is written
30  as:
31 
32  \verbatim
33  # Patch: <patch name>
34  <magSf1> <value1> <surfaceNormalGradient1>
35  <magSf2> <value2> <surfaceNormalGradient2>
36  <magSf3> <value3> <surfaceNormalGradient3>
37  ...
38  <magSfN> <valueN> <surfaceNormalGradientN>
39  \endverbatim
40 
41  and received as the constituent pieces of the `mixed' condition, i.e.
42 
43  \verbatim
44  # Patch: <patch name>
45  <value1> <gradient1> <valueFraction1>
46  <value2> <gradient2> <valueFraction2>
47  <value3> <gradient3> <valueFraction3>
48  ...
49  <valueN> <gradientN> <valueFractionN>
50  \endverbatim
51 
52  Data is sent/received as a single file for all patches from the directory
53 
54  \verbatim
55  $FOAM_CASE/<commsDir>
56  \endverbatim
57 
58  At start-up, the boundary creates a lock file, i.e..
59 
60  \verbatim
61  OpenFOAM.lock
62  \endverbatim
63 
64  ... to signal the external source to wait. During the boundary condition
65  update, boundary values are written to file, e.g.
66 
67  \verbatim
68  <fileName>.out
69  \endverbatim
70 
71  The lock file is then removed, instructing the external source to take
72  control of the program execution. When ready, the external program
73  should create the return values, e.g. to file
74 
75  \verbatim
76  <fileName>.in
77  \endverbatim
78 
79  ... and then re-instate the lock file. The boundary condition will then
80  read the return values, and pass program execution back to OpenFOAM.
81 
82 
83 Usage
84  \table
85  Property | Description | Required | Default value
86  commsDir | communications directory | yes |
87  file | transfer file name | yes |
88  waitInterval | interval [s] between file checks | no | 1
89  timeOut | time after which error invoked [s] |no |100*waitInterval
90  calcFrequency | calculation frequency | no | 1
91  initByExternal | external app to initialises values | yes |
92  log | log program control | no | no
93  \endtable
94 
95  Example of the boundary condition specification:
96  \verbatim
97  <patchName>
98  {
99  type externalCoupled;
100  commsDir "$FOAM_CASE/comms";
101  file data;
102  calcFrequency 1;
103  initByExternal yes;
104  }
105  \endverbatim
106 
107 See also
108  mixedFvPatchField
109 
110 SourceFiles
111  externalCoupledMixedFvPatchField.C
112 
113 \*---------------------------------------------------------------------------*/
114 
115 #ifndef externalCoupledMixedFvPatchField_H
116 #define externalCoupledMixedFvPatchField_H
117 
118 #include "mixedFvPatchFields.H"
119 #include "OFstream.H"
120 
121 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
122 
123 namespace Foam
124 {
125 
126 class IFstream;
127 
128 /*---------------------------------------------------------------------------*\
129  Class externalCoupledMixedFvPatchField Declaration
130 \*---------------------------------------------------------------------------*/
131 
132 template<class Type>
133 class externalCoupledMixedFvPatchField
134 :
135  public mixedFvPatchField<Type>
136 {
137  // Private Data
138 
139  //- Path to communications directory
140  fileName commsDir_;
141 
142  //- Name of data file
143  word fName_;
144 
145  //- Interval time between checking for return data [s]
146  label waitInterval_;
147 
148  //- Time out time [s]
149  label timeOut_;
150 
151  //- Calculation frequency
152  label calcFrequency_;
153 
154  //- Flag to indicate values are initialised by external application
155  bool initByExternal_;
156 
157  //- Log flag
158  bool log_;
159 
160  //- Master patch flag - controls when to pause/resume execution
161  // Note: only valid when collate option is selected
162  bool master_;
163 
164  //- Offsets in data file to start reading at correct position
165  List<List<label>> offsets_;
166 
167  //- Initialised flag
168  bool initialised_;
169 
170  //- List of coupled patch IDs
171  List<label> coupledPatchIndices_;
172 
173 
174  // Private Member Functions
175 
176  //- Initialise
177  void initialise(const fileName& transferFile);
178 
179  //- Set the master flag when collate option is selected
180  void setMaster(const labelList& patchIDs);
181 
182  //- Return the file path to the base communications directory
183  fileName baseDir() const;
184 
185  //- Write the geometry to the comms dir
186  void writeGeometry(OFstream& osPoints, OFstream& osFaces) const;
187 
188  //- Return the file path to the lock file
189  fileName lockFile() const;
190 
191  //- Create lock file
192  void createLockFile() const;
193 
194  //- Remove lock file
195  void removeLockFile() const;
196 
197  //- Wait for response from external source
198  void startWait() const;
199 
200  //- Wait for response from external source
201  void wait() const;
202 
203  //- Initialise input stream for reading
204  void initialiseRead(IFstream& is) const;
205 
206 
207 protected:
208 
209  // Protected Member Functions
210 
211  //- Read data from external source
212  virtual void readData(const fileName& transferFile);
213 
214  //- Write data for external source - calls transferData
215  virtual void writeData(const fileName& transferFile) const;
216 
217  //- Write header to transfer file
218  virtual void writeHeader(OFstream& os) const;
219 
220 
221 public:
222 
223  //- Runtime type information
224  TypeName("externalCoupled");
225 
226  //- Name of lock file
227  static word lockName;
228 
229  //- Name of patch key, e.g. '# Patch:' when looking for start of patch data
230  static string patchKey;
231 
232 
233  // Constructors
234 
235  //- Construct from patch, internal field and dictionary
237  (
238  const fvPatch&,
240  const dictionary&
241  );
242 
243  //- Construct by mapping given externalCoupledMixedFvPatchField
244  // onto a new patch
246  (
248  const fvPatch&,
250  const fieldMapper&
251  );
252 
253  //- Disallow copy without setting internal field reference
255  (
257  ) = delete;
258 
259  //- Copy constructor setting internal field reference
261  (
264  );
265 
266  //- Construct and return a clone setting internal field reference
268  (
270  ) const
271  {
272  return tmp<fvPatchField<Type>>
273  (
275  );
276  }
277 
278 
279  //- Destructor
281 
282 
283  // Member Functions
284 
285  //- Return the log flag
286  bool log() const
287  {
288  return log_;
289  }
290 
291  //- Return the master flag
292  bool master() const
293  {
294  return master_;
295  }
296 
297  //- Return the master flag
298  bool& master()
299  {
300  return master_;
301  }
302 
303  //- Evaluate the patch field
304  virtual void evaluate
305  (
307  );
308 
309  //- Transfer data for external source
310  virtual void transferData(OFstream& os) const;
311 
312  //- Write the geometry to the comms dir
313  void writeGeometry() const;
314 
315  //- Write
316  virtual void write(Ostream&) const;
317 };
318 
319 
320 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
321 
322 } // End namespace Foam
323 
324 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
325 
326 #ifdef NoRepository
328 #endif
329 
330 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
331 
332 #endif
333 
334 // ************************************************************************* //
Field with dimensions and associated with geometry type GeoMesh which is used to size the field and a...
Input from file stream.
Definition: IFstream.H:85
Output to file stream.
Definition: OFstream.H:86
An Ostream is an abstract base class for all output systems (streams, files, token lists,...
Definition: Ostream.H:57
commsTypes
Types of communications.
Definition: UPstream.H:65
A list of keyword definitions, which are a keyword followed by any number of values (e....
Definition: dictionary.H:162
This boundary condition provides an interface to an external application. Values are transferred as p...
virtual void evaluate(const Pstream::commsTypes commsType=Pstream::commsTypes::blocking)
Evaluate the patch field.
virtual void writeHeader(OFstream &os) const
Write header to transfer file.
static string patchKey
Name of patch key, e.g. '# Patch:' when looking for start of patch data.
externalCoupledMixedFvPatchField(const fvPatch &, const DimensionedField< Type, volMesh > &, const dictionary &)
Construct from patch, internal field and dictionary.
virtual void writeData(const fileName &transferFile) const
Write data for external source - calls transferData.
void writeGeometry() const
Write the geometry to the comms dir.
virtual void transferData(OFstream &os) const
Transfer data for external source.
TypeName("externalCoupled")
Runtime type information.
virtual void readData(const fileName &transferFile)
Read data from external source.
Abstract base class for field mapping.
Definition: fieldMapper.H:48
A class for handling file names.
Definition: fileName.H:82
tmp< fvPatchField< Type > > clone() const
Disallow clone without setting internal field reference.
Definition: fvPatchField.H:204
A finiteVolume patch using a polyPatch and a fvBoundaryMesh.
Definition: fvPatch.H:64
A class for managing temporary objects.
Definition: tmp.H:55
A class for handling words, derived from string.
Definition: word.H:62
Namespace for OpenFOAM.
intWM_LABEL_SIZE_t label
A label is an int32_t or int64_t as specified by the pre-processor macro WM_LABEL_SIZE.
Definition: label.H:59