src/fvm/fvm_periodicity.h Source File

| programmer's documentation

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
fvm_periodicity.h
Go to the documentation of this file.
1 #ifndef __FVM_PERIODICITY_H__
2 #define __FVM_PERIODICITY_H__
3
4 /*============================================================================
5 * Main structure for handling of periodicities
6 *============================================================================*/
7
8 /*
9 This file is part of Code_Saturne, a general-purpose CFD tool.
10
11 Copyright (C) 1998-2013 EDF S.A.
12
13 This program is free software; you can redistribute it and/or modify it under
14 the terms of the GNU General Public License as published by the Free Software
15 Foundation; either version 2 of the License, or (at your option) any later
16 version.
17
18 This program is distributed in the hope that it will be useful, but WITHOUT
19 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
20 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
21 details.
22
23 You should have received a copy of the GNU General Public License along with
24 this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
25 Street, Fifth Floor, Boston, MA 02110-1301, USA.
26 */
27
28 /*----------------------------------------------------------------------------*/
29
30 #include "cs_defs.h"
31
32 /*----------------------------------------------------------------------------
33 * Local headers
34 *----------------------------------------------------------------------------*/
35
36 #include "fvm_defs.h"
37
38 /*----------------------------------------------------------------------------*/
39
40 BEGIN_C_DECLS
41
42 /*=============================================================================
43 * Macro definitions
44 *============================================================================*/
45
46 /*============================================================================
47 * Type definitions
48 *============================================================================*/
49
50 /*----------------------------------------------------------------------------
51 * Periodicity types
52 *----------------------------------------------------------------------------*/
53
54 typedef enum {
55
56 FVM_PERIODICITY_NULL,
57 FVM_PERIODICITY_TRANSLATION,
58 FVM_PERIODICITY_ROTATION,
59 FVM_PERIODICITY_MIXED
60
61 } fvm_periodicity_type_t;
62
63 /*============================================================================
64 * Structure definitions
65 *============================================================================*/
66
67 typedef struct _fvm_periodicity_t fvm_periodicity_t;
68
69 /*=============================================================================
70 * Static global variables
71 *============================================================================*/
72
73 /* Names of periodicity type */
74
75 extern const char *fvm_periodicity_type_name[];
76
77 /*=============================================================================
78 * Public function prototypes
79 *============================================================================*/
80
81 /*----------------------------------------------------------------------------
82 * Create an empty periodicity definition structure.
83 *
84 * To create a composed periodicity, use fvm_periodicity_compose().
85 *
86 * parameters:
87 * equiv_tolerance <-- relative tolerance for identification of
88 * possibly equivalent directions
89 *
90 * returns:
91 * pointer to the created fvm_periodicity_t structure.
92 *---------------------------------------------------------------------------*/
93
94 fvm_periodicity_t *
95 fvm_periodicity_create(double equiv_tolerance);
96
97 /*----------------------------------------------------------------------------
98 * Destroy an fvm_periodicity_t structure.
99 *
100 * parameters:
101 * this_periodicity <-> pointer to structure that should be destroyed
102 *
103 * returns:
104 * NULL pointer
105 *---------------------------------------------------------------------------*/
106
107 fvm_periodicity_t *
108 fvm_periodicity_destroy(fvm_periodicity_t *this_periodicity);
109
110 /*----------------------------------------------------------------------------
111 * Return number of transformations associated with peridocity.
112 *
113 * parameters:
114 * this_periodicity <-- pointer to the periodicity structure
115 *
116 * returns:
117 * number of periodicity transformations
118 *---------------------------------------------------------------------------*/
119
120 int
121 fvm_periodicity_get_n_transforms(const fvm_periodicity_t *this_periodicity);
122
123 /*----------------------------------------------------------------------------
124 * Return number of periodicity combination levels.
125 *
126 * Combination level is 0 for single periodicity, and 1 or 2 for
127 * combinations of periodicities (2 max in 3d).
128 *
129 * parameters:
130 * this_periodicity <-- pointer to the periodicity structure
131 *
132 * returns:
133 * number of periodicity combination levels (1 to 3)
134 *---------------------------------------------------------------------------*/
135
136 int
137 fvm_periodicity_get_n_levels(const fvm_periodicity_t *this_periodicity);
138
139 /*----------------------------------------------------------------------------
140 * Return index of periodicity transform combination levels.
141 *
142 * Combination level is 0 for single periodicity, and 1 or 2 for
143 * combinations of periodicities (2 max in 3d).
144 *
145 * parameters:
146 * this_periodicity <-- pointer to the periodicity structure
147 * tr_level_index --> start index of first transform of each level
148 * (size: 3 + 1)
149 *---------------------------------------------------------------------------*/
150
151 void
152 fvm_periodicity_get_tr_level_idx(const fvm_periodicity_t *this_periodicity,
153 int tr_level_index[4]);
154
155 /*----------------------------------------------------------------------------
156 * Add a general periodicity direction.
157 *
158 * For each direction defined, two transformations are defined: direct
159 * and reverse. The id of the reverse transformation is equal to the
160 * id of the direct transformation + 1.
161 *
162 * parameters:
163 * this_periodicity <-- pointer to the periodicity structure
164 * external_num <-- external number (1 to n) associated with direction
165 * type <-- transformation type (translation or rotation)
166 * matrix <-- transformation matrix (3x4 matrix, 3 first rows
167 * of a homogeneous coordinates transformation
168 * matrix, with last row = [0 0 0 1])
169 *
170 * returns:
171 * id of the associated direct transformation.
172 *---------------------------------------------------------------------------*/
173
174 int
175 fvm_periodicity_add_by_matrix(fvm_periodicity_t *this_periodicity,
176 int external_num,
177 fvm_periodicity_type_t type,
178 double matrix[3][4]);
179
180 /*----------------------------------------------------------------------------
181 * Add a translation-type periodicity direction.
182 *
183 * For each direction defined, two transformations are defined: direct
184 * and reverse. The id of the reverse transformation is equal to the
185 * id of the direct transformation + 1.
186 *
187 * parameters:
188 * this_periodicity <-- pointer to the periodicity structure
189 * external_num <-- external number (1 to n) associated with direction
190 * translation <-- components of translation vector (3)
191 *
192 * returns:
193 * id of the associated direct transformation.
194 *---------------------------------------------------------------------------*/
195
196 int
197 fvm_periodicity_add_translation(fvm_periodicity_t *this_periodicity,
198 int external_num,
199 const double translation[3]);
200
201 /*----------------------------------------------------------------------------
202 * Add a rotation type periodicity direction.
203 *
204 * For each direction defined, two transformations are defined: direct
205 * and reverse. The id of the reverse transformation is equal to the
206 * id of the direct transformation + 1.
207 *
208 * parameters:
209 * this_periodicity <-- pointer to the periodicity structure
210 * external_num <-- external number (1 to n) associated with direction
211 * angle <-- rotation angle in degrees
212 * axis <-- components of rotation axis direction vector (3)
213 * invariant_point <-- components of invariant point (3)
214 *
215 * returns:
216 * id of the associated direct transformation.
217 *---------------------------------------------------------------------------*/
218
219 int
220 fvm_periodicity_add_rotation(fvm_periodicity_t *this_periodicity,
221 int external_num,
222 double angle,
223 const double axis[3],
224 const double invariant_point[3]);
225
226 /*----------------------------------------------------------------------------
227 * Return the periodicity transform id associated with an external number.
228 *
229 * parameters:
230 * this_periodicity <-- pointer to periodicity structure
231 * external_num <-- external number (1 to n) associated with direction
232 * direction <-- 1 for direct transformation, -1 for reverse
233 *
234 * returns:
235 * transformation id (0 to n-1), or -1 if not found.
236 *---------------------------------------------------------------------------*/
237
238 int
239 fvm_periodicity_get_transform_id(const fvm_periodicity_t *this_periodicity,
240 int external_num,
241 int direction);
242
243 /*----------------------------------------------------------------------------
244 * Return a periodicity transformation's type.
245 *
246 * parameters:
247 * this_periodicity <-- pointer to periodicity structure
248 * tr_id <-- id of transformation we are interested in
249 *
250 * returns:
251 * periodicity transform's type
252 *---------------------------------------------------------------------------*/
253
254 fvm_periodicity_type_t
255 fvm_periodicity_get_type(const fvm_periodicity_t *this_periodicity,
256 int tr_id);
257
258 /*----------------------------------------------------------------------------
259 * Return the periodicity transform reverse's id.
260 *
261 * parameters:
262 * this_periodicity <-- pointer to periodicity structure
263 * tr_id <-- id of transformation we are interested in
264 *
265 * returns:
266 * reverse transformation id (0 to n-1), or -1 if not found.
267 *---------------------------------------------------------------------------*/
268
269 int
270 fvm_periodicity_get_reverse_id(const fvm_periodicity_t *this_periodicity,
271 int tr_id);
272
273 /*----------------------------------------------------------------------------
274 * Return a periodicity transformation's parents.
275 *
276 * A standard transformation has combination level 0, and no parents.
277 * Transformations built from combination of 2 parents have combination
278 * level 1, and those built from the combination of 3 parents have
279 * combination level 2.
280 *
281 * Level 2 transformations are built from a combination of a level 0
282 * transformation with a level 1 transformation (itself a combination of
283 * 2 level 0 transformations).
284 *
285 * parameters:
286 * this_periodicity <-- pointer to periodicity structure
287 * tr_id <-- id of transformation we are interested in
288 * parent_ids --> parent ids, or -1 (size: 2)
289 *---------------------------------------------------------------------------*/
290
291 void
292 fvm_periodicity_get_parent_ids(const fvm_periodicity_t *this_periodicity,
293 int tr_id,
294 int parent_ids[2]);
295
296 /*----------------------------------------------------------------------------
297 * Return a periodicity transformation's component ids.
298 *
299 * A standard transformation has combination level 0, and no parents.
300 * Transformations built from combination of 2 parents have combination
301 * level 1, and those built from the combination of 3 parents have
302 * combination level 2.
303 *
304 * Level 2 transformations are built from a combination of a level 0
305 * transformation with a level 1 transformation (itself a combination of
306 * 2 level 0 transformations). Component ids allow direct access to the 3
307 * corresponding level 0 combinations.
308 *
309 * parameters:
310 * this_periodicity <-- pointer to periodicity structure
311 * tr_id <-- id of transformation we are interested in
312 * component_ids --> component ids, or -1 (size: 3)
313 *---------------------------------------------------------------------------*/
314
315 void
316 fvm_periodicity_get_components(const fvm_periodicity_t *this_periodicity,
317 int tr_id,
318 int component_ids[3]);
319
320 /*----------------------------------------------------------------------------
321 * Return a periodicity transformation's first equivalent transform id.
322 *
323 * If multiple transformations are equivalent, each will point to
324 * the previous equivalent transformation, defining a reversed linked list.
325 *
326 * parameters:
327 * this_periodicity <-- pointer to periodicity structure
328 * tr_id <-- id of transformation we are interested in
329 *
330 * returns:
331 * id of first equivalent transformation
332 *---------------------------------------------------------------------------*/
333
334 int
335 fvm_periodicity_get_equiv_id(const fvm_periodicity_t *this_periodicity,
336 int tr_id);
337
338 /*----------------------------------------------------------------------------
339 * Return a periodicity transformation's matrix.
340 *
341 * parameters:
342 * this_periodicity <-- pointer to periodicity structure
343 * tr_id <-- id of transformation we are interested in
344 * matrix --> coefficients of transformation matrix
345 *
346 * returns:
347 * periodicity transform's matrix
348 *---------------------------------------------------------------------------*/
349
350 void
351 fvm_periodicity_get_matrix(const fvm_periodicity_t *this_periodicity,
352 int tr_id,
353 double matrix[3][4]);
354
355 /*----------------------------------------------------------------------------
356 * Complete periodicity information with combined transformations.
357 *
358 * This function should only be called once, after all base periodicity
359 * transforms have been defined. It returns immediately if combined
360 * transforms are already defined.
361 *
362 * parameters:
363 * this_periodicity <-> pointer to the periodicity structure
364 * abort_on_error <-- 0: non-commuting combinations are discarded
365 * 1: abort in presence of non-commuting combinations
366 *---------------------------------------------------------------------------*/
367
368 void
369 fvm_periodicity_combine(fvm_periodicity_t *this_periodicity,
370 int abort_on_error);
371
372 /*----------------------------------------------------------------------------
373 * Dump fvm_periodicity_t structure
374 *
375 * parameters:
376 * this_periodicity <-- pointer to the periodicity structure
377 *---------------------------------------------------------------------------*/
378
379 void
380 fvm_periodicity_dump(const fvm_periodicity_t *this_periodicity);
381
382 /*----------------------------------------------------------------------------*/
383
384 END_C_DECLS
385
386 #endif /* __FVM_PERIODICITY_H__ */