1 #ifndef __CS_XDEF_H__
2 #define __CS_XDEF_H__
3
4 /*============================================================================
5 * Functions to handle extended definitions of quantities
6 *============================================================================*/
7
8 /*
9 This file is part of Code_Saturne, a general-purpose CFD tool.
10
11 Copyright (C) 1998-2021 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 /*----------------------------------------------------------------------------
31 * Local headers
32 *----------------------------------------------------------------------------*/
33
34 #include <string.h>
35
36 #include "cs_base.h"
37 #include "cs_boundary_zone.h"
38 #include "cs_param_types.h"
39 #include "cs_quadrature.h"
40 #include "cs_volume_zone.h"
41
42 /*----------------------------------------------------------------------------*/
43
44 BEGIN_C_DECLS
45
46 /*============================================================================
47 * Macro definitions
48 *============================================================================*/
49
50 /*============================================================================
51 * Type definitions
52 *============================================================================*/
53
54 /*----------------------------------------------------------------------------*/
55 /*!
56 * \brief Destroy an input data structure.
57 * Complex data structure can be used when a \ref cs_xdef_t structure
58 * is defined by an analytic function, a DoF function or a time
59 * function. Please refer to \ref cs_xdef_analytic_context_t,
60 * \ref cs_xdef_time_func_context_t or \ref cs_xdef_dof_context_t
61 *
62 * \param[in, out] input pointer to an input structure associated to a
63 * context structure
64 *
65 * \return a NULL pointer
66 */
67 /*----------------------------------------------------------------------------*/
68
69 typedef void *
70 (cs_xdef_free_input_t)(void *input);
71
72 /*!
73 * \enum cs_xdef_type_t
74 *
75 * \var CS_XDEF_BY_ANALYTIC_FUNCTION
76 * Definition relying on a \ref cs_analytic_func_t function pointer
77 *
78 * \var CS_XDEF_BY_ARRAY
79 * Definition based on an array
80 *
81 * \var CS_XDEF_BY_DOF_FUNCTION
82 * Definition relying on a \ref cs_dof_func_t function pointer
83 *
84 * \var CS_XDEF_BY_FIELD
85 * Definition based on a field (see \ref cs_field_t)
86 *
87 * \var CS_XDEF_BY_FUNCTION
88 * Definition relying on a generic user-defined function. TODO
89 *
90 * \var CS_XDEF_BY_QOV
91 * QOV = Quantity Over a Volume
92 * Definition which enables to spread a given quantity inside a volume.
93 * Useful to initialized a tracer in a subdomain for instance.
94 *
95 * \var CS_XDEF_BY_SUB_DEFINITIONS
96 * Definition relying on a combination of other CS_XDEF_***
97 * This kind of definition is useful for the definition of a property
98 * as the product of two existing ones.
99 *
100 * \var CS_XDEF_BY_TIME_FUNCTION
101 * Definition relying on a function for setting the time step (see
102 * \ref cs_time_func_t)
103 *
104 * \var CS_XDEF_BY_VALUE
105 * Simple definition by a constant value
106 */
107
108 typedef enum {
109
110 CS_XDEF_BY_ANALYTIC_FUNCTION,
111 CS_XDEF_BY_ARRAY,
112 CS_XDEF_BY_DOF_FUNCTION,
113 CS_XDEF_BY_FIELD,
114 CS_XDEF_BY_FUNCTION,
115 CS_XDEF_BY_QOV,
116 CS_XDEF_BY_SUB_DEFINITIONS,
117 CS_XDEF_BY_TIME_FUNCTION,
118 CS_XDEF_BY_VALUE,
119
120 CS_N_XDEF_TYPES
121
122 } cs_xdef_type_t;
123
124 /*!
125 * \enum cs_xdef_support_t
126 *
127 * \var CS_XDEF_SUPPORT_TIME
128 * Definition for the time step. No zone is attached.
129 *
130 * \var CS_XDEF_SUPPORT_BOUNDARY
131 * Definition for a boundary zone. Zones are attached to a list of boundary
132 * faces.
133 *
134 * \var CS_XDEF_SUPPORT_VOLUME
135 * Definition for a volumic zone. Zones are attached to a list of cells.
136 */
137
138 typedef enum {
139
140 CS_XDEF_SUPPORT_TIME, /* support for time step description */
141 CS_XDEF_SUPPORT_BOUNDARY, /* zones attached to boundary faces */
142 CS_XDEF_SUPPORT_VOLUME,
143
144 CS_N_XDEF_SUPPORTS
145
146 } cs_xdef_support_t;
147
148 /*!
149 * \struct cs_xdef_t
150 * \brief Structure storing medata for defining a quantity in a very flexible
151 * way
152 */
153
154 typedef struct {
155
156 /*! \var dim
157 * dimension of the values attached to this description
158 *
159 * \var type
160 * type of definition (see \ref cs_xdef_type_t)
161 *
162 * \var z_id
163 * id related to a zone (volume or boundary) for this definition
164 *
165 * \var support
166 * support for this definition (see \ref cs_xdef_support_t)
167 *
168 * \var state
169 * Flag storing state of the values related to this definition
170 * Example: steady, uniform, cellwise...
171 *
172 * \var meta
173 * Flag storing in a condensed way metadata about the description.
174 * These metadata may vary according to the object on which the description
175 * applies.
176 *
177 * \var qtype
178 * type of quadrature to use for evaluating the description (see
179 * \ref cs_quadrature_type_t)
180 *
181 * \var context
182 * Pointer to a structure cast on-the-fly according to the type of description
183 * May be set to NULL or \ref cs_xdef_array_context_t or
184 * \ref cs_xdef_analytic_context_t or \ref cs_xdef_time_func_context_t or
185 * \ref cs_xdef_dof_context_t
186 */
187
188 int dim;
189 cs_xdef_type_t type;
190 int z_id;
191 cs_xdef_support_t support;
192
193 cs_flag_t state;
194 cs_flag_t meta;
195
196 cs_quadrature_type_t qtype;
197
198 void *context;
199
200 } cs_xdef_t;
201
202 /*!
203 * \struct cs_xdef_array_context_t
204 * \brief Context structure when an array is used for the definition
205 */
206
207 typedef struct {
208
209 /*!
210 * \var z_id
211 * id related to a zone (volume or boundary) for this definition
212 *
213 * \var stride
214 * Stride to access the array values
215 *
216 * \var loc
217 * Flag to know where are defined array values
218 *
219 * \var values
220 * Array values
221 *
222 * \var index
223 * Optional index for accessing to the values. One assumes that the lifecycle
224 * of this buffer is managed outside (pointer to a cs_adjacency_t stored
225 * either in the \ref cs_cdo_connect_t struct. or the \ref cs_mesh_t struct.
226 *
227 * \var is_owner
228 * If true the lifecycle of the values is managed by the cs_xdef_t structure.
229 * Otherwise, the lifecycle is managed by the calling code.
230 */
231
232 int z_id;
233 int stride;
234 cs_flag_t loc;
235 cs_real_t *values;
236 cs_lnum_t *index;
237 bool is_owner;
238
239 } cs_xdef_array_context_t;
240
241 /*!
242 * \struct cs_xdef_analytic_context_t
243 * \brief Context structure when a definition by analytic function is used
244 */
245
246 typedef struct {
247
248 /*! \var z_id
249 * id related to a zone (volume or boundary) for this definition
250 */
251 int z_id;
252
253 /*! \var func
254 * pointer to a \ref cs_analytic_func_t to call
255 */
256 cs_analytic_func_t *func;
257
258 /*! \var input
259 * NULL or pointer to a structure cast on-the-fly for additional information
260 * used in the function
261 */
262 void *input;
263
264 /*! \var free_input
265 * NULL or pointer to a function to free a given input structure
266 */
267 cs_xdef_free_input_t *free_input;
268
269 } cs_xdef_analytic_context_t;
270
271 /*!
272 * \struct cs_xdef_dof_context_t
273 * \brief Context structure when a definition by DoF function is used
274 */
275
276 typedef struct {
277
278 /*! \var z_id
279 * id related to a zone (volume or boundary) for this definition
280 */
281 int z_id;
282
283 /*! \var loc
284 * Flag to know which type of entities are given as parameter in the
285 * \ref cs_dof_func_t
286 */
287 cs_flag_t loc;
288
289 /*! \var func
290 * pointer to a \ref cs_dof_func_t to call
291 */
292 cs_dof_func_t *func;
293
294 /*! \var input
295 * NULL or pointer to a structure cast on-the-fly for additional information
296 * used in the function
297 */
298 void *input;
299
300 /*! \var free_input
301 * NULL or pointer to a function to free a given input structure
302 */
303 cs_xdef_free_input_t *free_input;
304
305 } cs_xdef_dof_context_t;
306
307 /*!
308 * \struct cs_xdef_time_func_context_t
309 * \brief Context structure when a time step function is used for the definition
310 */
311
312 typedef struct {
313
314 /*! \var func
315 * pointer to a \ref cs_time_func_t to call
316 */
317 cs_time_func_t *func;
318
319 /*! \var input
320 * NULL or pointer to a structure cast on-the-fly for additional information
321 * used in the function
322 */
323 void *input;
324
325 /*! \var free_input
326 * NULL or pointer to a function to free a given input structure
327 */
328 cs_xdef_free_input_t *free_input;
329
330 } cs_xdef_time_func_context_t;
331
332 /*============================================================================
333 * Public function prototypes
334 *============================================================================*/
335
336 /*----------------------------------------------------------------------------*/
337 /*!
338 * \brief Retrieve the volume zone if from the zone name (If name = NULL or
339 * has an empty length, all entities are selected)
340 *
341 * \param[in] z_name name of the zone
342 *
343 * \return the id of the related zone
344 */
345 /*----------------------------------------------------------------------------*/
346
347 static inline int
cs_get_vol_zone_id(const char * z_name)348 cs_get_vol_zone_id(const char *z_name)
349 {
350 int z_id = 0;
351 if (z_name != NULL) {
352 if (strlen(z_name) > 0) {
353 const cs_zone_t *z = cs_volume_zone_by_name(z_name);
354 z_id = z->id;
355 }
356 }
357 return z_id;
358 }
359
360 /*----------------------------------------------------------------------------*/
361 /*!
362 * \brief Retrieve the boundary zone if from the zone name (If name = NULL or
363 * has an empty length, all entities are selected)
364 *
365 * \param[in] z_name name of the zone
366 *
367 * \return the id of the related zone
368 */
369 /*----------------------------------------------------------------------------*/
370
371 static inline int
cs_get_bdy_zone_id(const char * z_name)372 cs_get_bdy_zone_id(const char *z_name)
373 {
374 int z_id = 0;
375 if (z_name != NULL) {
376 if (strlen(z_name) > 0) {
377 const cs_zone_t *z = cs_boundary_zone_by_name(z_name);
378 z_id = z->id;
379 }
380 }
381 return z_id;
382 }
383
384 /*----------------------------------------------------------------------------*/
385 /*!
386 * \brief Retrieve the value associated to the given definition.
387 * This should be a definition by value and the dimension should be
388 * equal to one.
389 *
390 * \param[in] def pointer to a cs_xdef_t structure
391 *
392 * \return the value of the definition
393 */
394 /*----------------------------------------------------------------------------*/
395
396 inline static cs_real_t
cs_xdef_get_scalar_value(cs_xdef_t * def)397 cs_xdef_get_scalar_value(cs_xdef_t *def)
398 {
399 assert(def != NULL);
400 assert(def->dim == 1);
401 assert(def->type == CS_XDEF_BY_VALUE);
402
403 cs_real_t *value = (cs_real_t *)def->context;
404
405 return value[0];
406 }
407
408 /*----------------------------------------------------------------------------*/
409 /*!
410 * \brief Retrieve the values associated to the given definition.
411 * This should be a definition by array
412 *
413 * \param[in] def pointer to a cs_xdef_t structure
414 *
415 * \return the pointer to the array of values
416 */
417 /*----------------------------------------------------------------------------*/
418
419 inline static cs_real_t *
cs_xdef_get_array(cs_xdef_t * def)420 cs_xdef_get_array(cs_xdef_t *def)
421 {
422 assert(def != NULL);
423 assert(def->type == CS_XDEF_BY_ARRAY);
424
425 cs_xdef_array_context_t *ai = (cs_xdef_array_context_t *)def->context;
426
427 return ai->values;
428 }
429
430 /*============================================================================
431 * Public function prototypes
432 *============================================================================*/
433
434 /*----------------------------------------------------------------------------*/
435 /*!
436 * \brief Allocate and initialize a new cs_xdef_t structure based on volumic
437 * elements
438 *
439 * \param[in] type type of definition
440 * \param[in] dim dimension of the values to define
441 * \param[in] z_id volume zone id
442 * \param[in] state flag to know if this uniform, cellwise, steady...
443 * \param[in] meta metadata associated to this description
444 * \param[in] context pointer to a structure
445 *
446 * \return a pointer to the new cs_xdef_t structure
447 */
448 /*----------------------------------------------------------------------------*/
449
450 cs_xdef_t *
451 cs_xdef_volume_create(cs_xdef_type_t type,
452 int dim,
453 int z_id,
454 cs_flag_t state,
455 cs_flag_t meta,
456 void *context);
457
458 /*----------------------------------------------------------------------------*/
459 /*!
460 * \brief Allocate and initialize a new cs_xdef_t structure based on boundary
461 * elements
462 *
463 * \param[in] type type of definition
464 * \param[in] dim dimension of the values to define
465 * \param[in] z_id volume zone id
466 * \param[in] state flag to know if this uniform, cellwise, steady...
467 * \param[in] meta metadata associated to this description
468 * \param[in] context pointer to a structure
469 *
470 * \return a pointer to the new cs_xdef_t structure
471 */
472 /*----------------------------------------------------------------------------*/
473
474 cs_xdef_t *
475 cs_xdef_boundary_create(cs_xdef_type_t type,
476 int dim,
477 int z_id,
478 cs_flag_t state,
479 cs_flag_t meta,
480 void *context);
481
482 /*----------------------------------------------------------------------------*/
483 /*!
484 * \brief Allocate and initialize a new cs_xdef_t structure for setting the
485 * time step
486 *
487 * \param[in] type type of definition
488 * \param[in] state flag to know if this uniform, cellwise, steady...
489 * \param[in] meta metadata associated to this description
490 * \param[in] context pointer to a structure storing the parameters (cast
491 * on-the-fly according to the type of definition)
492 *
493 * \return a pointer to the new cs_xdef_t structure
494 */
495 /*----------------------------------------------------------------------------*/
496
497 cs_xdef_t *
498 cs_xdef_timestep_create(cs_xdef_type_t type,
499 cs_flag_t state,
500 cs_flag_t meta,
501 void *context);
502
503 /*----------------------------------------------------------------------------*/
504 /*!
505 * \brief Free a cs_xdef_t structure
506 *
507 * \param[in, out] d pointer to a cs_xdef_t structure
508 *
509 * \return NULL
510 */
511 /*----------------------------------------------------------------------------*/
512
513 cs_xdef_t *
514 cs_xdef_free(cs_xdef_t *d);
515
516 /*----------------------------------------------------------------------------*/
517 /*!
518 * \brief copy a cs_xdef_t structure
519 *
520 * \param[in] src pointer to a cs_xdef_t structure to copy
521 *
522 * \return a pointer to a new allocated cs_xdef_t structure
523 */
524 /*----------------------------------------------------------------------------*/
525
526 cs_xdef_t *
527 cs_xdef_copy(cs_xdef_t *src);
528
529 /*----------------------------------------------------------------------------*/
530 /*!
531 * \brief In the case of a definition by an analytic function, a time function
532 * or a function relying on degrees of freedom (DoFs), this function
533 * allows one to set a more or less complex input data structure. This
534 * call should be done before the first evaluation call of the
535 * associated cs_xdef_t structure.
536 *
537 * \param[in, out] d pointer to a cs_xdef_t structure
538 * \param[in] input pointer to an input structure
539 */
540 /*----------------------------------------------------------------------------*/
541
542 void
543 cs_xdef_set_input_context(cs_xdef_t *d,
544 void *input);
545
546 /*----------------------------------------------------------------------------*/
547 /*!
548 * \brief In case of a definition by an analytic function, a time function or a
549 * function relying on degrees of freedom (DoFs). One can set a function
550 * to free a complex input data structure (please refer to \ref
551 * cs_xdef_free_input_t) for more details.
552 *
553 * \param[in, out] d pointer to a cs_xdef_t structure
554 * \param[in] free_input pointer to a function which free the input
555 * structure
556 */
557 /*----------------------------------------------------------------------------*/
558
559 void
560 cs_xdef_set_free_input_function(cs_xdef_t *d,
561 cs_xdef_free_input_t *free_input);
562
563 /*----------------------------------------------------------------------------*/
564 /*!
565 * \brief In case of definition by array, set the array after having added
566 * this definition
567 *
568 * \param[in, out] d pointer to a cs_xdef_t structure
569 * \param[in] is_owner manage or not the lifecycle of the array values
570 * \param[in] array values
571 */
572 /*----------------------------------------------------------------------------*/
573
574 void
575 cs_xdef_set_array(cs_xdef_t *d,
576 bool is_owner,
577 cs_real_t *array);
578
579 /*----------------------------------------------------------------------------*/
580 /*!
581 * \brief In case of definition by array, set the index to get access to the
582 * array values.
583 *
584 * \param[in, out] d pointer to a cs_xdef_t structure
585 * \param[in] array_index index on array values
586 */
587 /*----------------------------------------------------------------------------*/
588
589 void
590 cs_xdef_set_array_index(cs_xdef_t *d,
591 cs_lnum_t *array_index);
592
593 /*----------------------------------------------------------------------------*/
594 /*!
595 * \brief Set the type of quadrature to use for evaluating the given
596 * description
597 *
598 * \param[in, out] d pointer to a cs_xdef_t structure
599 * \param[in] qtype type of quadrature
600 */
601 /*----------------------------------------------------------------------------*/
602
603 void
604 cs_xdef_set_quadrature(cs_xdef_t *d,
605 cs_quadrature_type_t qtype);
606
607 /*----------------------------------------------------------------------------*/
608 /*!
609 * \brief Get the type of quadrature to use for evaluating the given
610 * description
611 *
612 * \param[in] d pointer to a cs_xdef_t structure
613 *
614 * \return the type of quadrature
615 */
616 /*----------------------------------------------------------------------------*/
617
618 cs_quadrature_type_t
619 cs_xdef_get_quadrature(cs_xdef_t *d);
620
621 /*----------------------------------------------------------------------------*/
622 /*!
623 * \brief Retrieve the flag dedicated to the state
624 *
625 * \param[in] d pointer to a cs_xdef_t structure
626 *
627 * \return the value of the flag
628 */
629 /*----------------------------------------------------------------------------*/
630
631 cs_xdef_type_t
632 cs_xdef_get_type(const cs_xdef_t *d);
633
634 /*----------------------------------------------------------------------------*/
635 /*!
636 * \brief Retrieve the flag dedicated to the state
637 *
638 * \param[in] d pointer to a cs_xdef_t structure
639 *
640 * \return the value of the flag
641 */
642 /*----------------------------------------------------------------------------*/
643
644 cs_flag_t
645 cs_xdef_get_state_flag(const cs_xdef_t *d);
646
647 /*----------------------------------------------------------------------------*/
648 /*!
649 * \brief Output the settings related to a cs_xdef_t structure
650 *
651 * \param[in] prefix optional string
652 * \param[in] d pointer to a cs_xdef_t structure
653 */
654 /*----------------------------------------------------------------------------*/
655
656 void
657 cs_xdef_log(const char *prefix,
658 const cs_xdef_t *d);
659
660 /*----------------------------------------------------------------------------*/
661 /*!
662 * \brief Retrieve a pointer to the cs_xdef_type's name string
663 *
664 * \param[in] xdef_type type to query
665 *
666 * \return a pointer to mathing name string
667 */
668 /*----------------------------------------------------------------------------*/
669
670 const char *
671 cs_xdef_type_get_name(cs_xdef_type_t xdef_type);
672
673 /*----------------------------------------------------------------------------*/
674
675 END_C_DECLS
676
677 #endif /* __CS_XDEF_H__ */
678