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-2020 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  //- Convenience typedefs
140  typedef externalCoupledMixedFvPatchField<Type> patchType;
141  typedef GeometricField<Type, fvPatchField, volMesh> volFieldType;
142 
143  //- Path to communications directory
144  fileName commsDir_;
145 
146  //- Name of data file
147  word fName_;
148 
149  //- Interval time between checking for return data [s]
150  label waitInterval_;
151 
152  //- Time out time [s]
153  label timeOut_;
154 
155  //- Calculation frequency
156  label calcFrequency_;
157 
158  //- Flag to indicate values are initialised by external application
159  bool initByExternal_;
160 
161  //- Log flag
162  bool log_;
163 
164  //- Master patch flag - controls when to pause/resume execution
165  // Note: only valid when collate option is selected
166  bool master_;
167 
168  //- Offsets in data file to start reading at correct position
169  List<List<label>> offsets_;
170 
171  //- Initialised flag
172  bool initialised_;
173 
174  //- List of coupled patch IDs
175  List<label> coupledPatchIDs_;
176 
177 
178  // Private Member Functions
179 
180  //- Initialise
181  void initialise(const fileName& transferFile);
182 
183  //- Set the master flag when collate option is selected
184  void setMaster(const labelList& patchIDs);
185 
186  //- Return the file path to the base communications directory
187  fileName baseDir() const;
188 
189  //- Write the geometry to the comms dir
190  void writeGeometry(OFstream& osPoints, OFstream& osFaces) const;
191 
192  //- Return the file path to the lock file
193  fileName lockFile() const;
194 
195  //- Create lock file
196  void createLockFile() const;
197 
198  //- Remove lock file
199  void removeLockFile() const;
200 
201  //- Wait for response from external source
202  void startWait() const;
203 
204  //- Wait for response from external source
205  void wait() const;
206 
207  //- Initialise input stream for reading
208  void initialiseRead(IFstream& is) const;
209 
210 
211 protected:
212 
213  // Protected Member Functions
214 
215  //- Read data from external source
216  virtual void readData(const fileName& transferFile);
217 
218  //- Write data for external source - calls transferData
219  virtual void writeData(const fileName& transferFile) const;
220 
221  //- Write header to transfer file
222  virtual void writeHeader(OFstream& os) const;
223 
224 
225 public:
226 
227  //- Runtime type information
228  TypeName("externalCoupled");
229 
230  //- Name of lock file
231  static word lockName;
232 
233  //- Name of patch key, e.g. '# Patch:' when looking for start of patch data
234  static string patchKey;
235 
236 
237  // Constructors
238 
239  //- Construct from patch and internal field
241  (
242  const fvPatch&,
244  );
245 
246  //- Construct from patch, internal field and dictionary
248  (
249  const fvPatch&,
251  const dictionary&
252  );
253 
254  //- Construct by mapping given externalCoupledMixedFvPatchField
255  // onto a new patch
257  (
259  const fvPatch&,
261  const fvPatchFieldMapper&
262  );
263 
264  //- Disallow copy without setting internal field reference
266  (
268  ) = delete;
269 
270  //- Copy constructor setting internal field reference
272  (
275  );
276 
277  //- Construct and return a clone setting internal field reference
279  (
281  ) const
282  {
283  return tmp<fvPatchField<Type>>
284  (
286  );
287  }
288 
289 
290  //- Destructor
292 
293 
294  // Member Functions
295 
296  //- Return the log flag
297  bool log() const
298  {
299  return log_;
300  }
301 
302  //- Return the master flag
303  bool master() const
304  {
305  return master_;
306  }
307 
308  //- Return the master flag
309  bool& master()
310  {
311  return master_;
312  }
313 
314  //- Evaluate the patch field
315  virtual void evaluate
316  (
318  );
319 
320  //- Transfer data for external source
321  virtual void transferData(OFstream& os) const;
322 
323  //- Write the geometry to the comms dir
324  void writeGeometry() const;
325 
326  //- Write
327  virtual void write(Ostream&) const;
328 };
329 
330 
331 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
332 
333 } // End namespace Foam
334 
335 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
337 #ifdef NoRepository
339 #endif
340 
341 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
343 #endif
344 
345 // ************************************************************************* //
This boundary condition provides an interface to an external application. Values are transferred as p...
virtual void transferData(OFstream &os) const
Transfer data for external source.
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
A class for handling file names.
Definition: fileName.H:79
void writeGeometry() const
Write the geometry to the comms dir.
A list of keyword definitions, which are a keyword followed by any number of values (e...
Definition: dictionary.H:156
commsTypes
Types of communications.
Definition: UPstream.H:64
Output to file stream.
Definition: OFstream.H:82
A finiteVolume patch using a polyPatch and a fvBoundaryMesh.
Definition: fvPatch.H:62
virtual void evaluate(const Pstream::commsTypes commsType=Pstream::commsTypes::blocking)
Evaluate the patch field.
TypeName("externalCoupled")
Runtime type information.
virtual void writeHeader(OFstream &os) const
Write header to transfer file.
A class for handling words, derived from string.
Definition: word.H:59
static string patchKey
Name of patch key, e.g. &#39;# Patch:&#39; when looking for start of patch data.
Foam::fvPatchFieldMapper.
An Ostream is an abstract base class for all output systems (streams, files, token lists...
Definition: Ostream.H:54
Input from file stream.
Definition: IFstream.H:81
virtual void readData(const fileName &transferFile)
Read data from external source.
virtual void writeData(const fileName &transferFile) const
Write data for external source - calls transferData.
externalCoupledMixedFvPatchField(const fvPatch &, const DimensionedField< Type, volMesh > &)
Construct from patch and internal field.
Field with dimensions and associated with geometry type GeoMesh which is used to size the field and a...
A class for managing temporary objects.
Definition: PtrList.H:53
tmp< fvPatchField< Type > > clone() const
Disallow clone without setting internal field reference.
Definition: fvPatchField.H:199
Namespace for OpenFOAM.