programmer's documentation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
cs_field.h
Go to the documentation of this file.
1 #ifndef __CS_FIELD_H__
2 #define __CS_FIELD_H__
3 
4 /*============================================================================
5  * Field management.
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 /*----------------------------------------------------------------------------
31  * Local headers
32  *----------------------------------------------------------------------------*/
33 
34 #include "cs_defs.h"
35 
36 /*----------------------------------------------------------------------------*/
37 
39 
40 /*=============================================================================
41  * Macro definitions
42  *============================================================================*/
43 
44 /*
45  * Field property type
46  */
47 
48 #define CS_FIELD_INTENSIVE (1 << 0)
49 #define CS_FIELD_EXTENSIVE (1 << 1)
50 
51 /* Field category */
52 
53 #define CS_FIELD_VARIABLE (1 << 2)
54 #define CS_FIELD_PROPERTY (1 << 3)
55 #define CS_FIELD_POSTPROCESS (1 << 4)
56 #define CS_FIELD_ACCUMULATOR (1 << 5)
57 
58 #define CS_FIELD_USER (1 << 6)
59 
60 /*============================================================================
61  * Type definitions
62  *============================================================================*/
63 
64 /* Field handling error types */
65 /*----------------------------*/
66 
67 typedef enum {
68 
74 
76 
77 /* Field boundary condition descriptor (for variables) */
78 /*-----------------------------------------------------*/
79 
80 typedef struct {
81 
82  int location_id; /* Id of matching location */
83 
84  cs_real_t *a; /* Explicit coefficient */
85  cs_real_t *b; /* Implicit coefficient */
86  cs_real_t *af; /* Explicit coefficient for flux */
87  cs_real_t *bf; /* Implicit coefficient for flux */
88  cs_real_t *ad; /* Explicit coefficient for divergence */
89  cs_real_t *bd; /* Implicit coefficient for divergence */
90  cs_real_t *ac; /* Explicit coefficient for convection */
91  cs_real_t *bc; /* Implicit coefficient for convection */
92 
94 
95 /* Field descriptor */
96 /*------------------*/
97 
98 typedef struct {
99 
100  const char *name; /* Canonical name */
101 
102  int id; /* Field id */
103  int type; /* Field type flag */
104 
105  int dim; /* Field dimension */
106  bool interleaved; /* is field interleaved ? */
107 
108  int location_id; /* Id of matching location */
109 
110  int n_time_vals; /* Number of time values (1 or 2) */
111 
112  cs_real_t *val; /* For each active location, pointer
113  to matching values array */
114 
115  cs_real_t *val_pre; /* For each active location, pointer
116  to matching previous values array
117  (if n_time_vals == 2) */
118 
119  cs_field_bc_coeffs_t *bc_coeffs; /* Boundary condition coefficients,
120  for variable type fields */
121 
122  bool is_owner; /* Ownership flag for values
123  and boundary coefficients */
124 
125 } cs_field_t;
126 
127 /*----------------------------------------------------------------------------
128  * Function pointer for structure associated to field key
129  *
130  * parameters:
131  * t <-- pointer to structure
132  *----------------------------------------------------------------------------*/
133 
134 typedef void
135 (cs_field_log_key_struct_t) (const void *t);
136 
137 /*=============================================================================
138  * Public function prototypes
139  *============================================================================*/
140 
141 /*----------------------------------------------------------------------------
142  * Return the number of defined fields.
143  *
144  * returns:
145  * number of defined fields.
146  *----------------------------------------------------------------------------*/
147 
148 int
149 cs_field_n_fields(void);
150 
151 /*----------------------------------------------------------------------------
152  * Create a field descriptor.
153  *
154  * parameters:
155  * name <-- field name
156  * type_flag <-- mask of field property and category values
157  * location_id <-- id of associated location
158  * dim <-- field dimension (number of components)
159  * interleaved <-- indicate if values are interleaved
160  * (ignored if number of components < 2)
161  * has_previous <-- maintain values at the previous time step ?
162  *
163  * returns:
164  * pointer to new field.
165  *----------------------------------------------------------------------------*/
166 
167 cs_field_t *
168 cs_field_create(const char *name,
169  int type_flag,
170  int location_id,
171  int dim,
172  bool interleaved,
173  bool has_previous);
174 
175 /*----------------------------------------------------------------------------
176  * Allocate arrays for field values.
177  *
178  * parameters:
179  * f <-- pointer to field structure
180  *----------------------------------------------------------------------------*/
181 
182 void
184 
185 /*----------------------------------------------------------------------------
186  * Map existing value arrays to field descriptor.
187  *
188  * parameters:
189  * f <-> pointer to field structure
190  * val <-- pointer to array of values
191  * val_pre <-- pointer to array of previous values, or NULL
192  *----------------------------------------------------------------------------*/
193 
194 void
196  cs_real_t *val,
197  cs_real_t *val_pre);
198 
199 /*----------------------------------------------------------------------------
200  * Allocate boundary condition coefficient arrays.
201  *
202  * For fields on location CS_MESH_LOCATION_CELLS, boundary conditions
203  * are located on CS_MESH_LOCATION_BOUNDARY_FACES.
204  *
205  * Boundary condition coefficients are not currently supported for other
206  * locations (though support could be added by mapping a boundary->location
207  * indirection array in the cs_mesh_location_t structure).
208  *
209  * For multidimensional fields, arrays are assumed to have the same
210  * interleaving behavior as the field, unless components are coupled.
211  *
212  * For multidimensional fields with coupled components, interleaving
213  * is the norm, and implicit b and bf coefficient arrays are arrays of
214  * block matrices, not vectors, so the number of entries for each boundary
215  * face is dim*dim instead of dim.
216  *
217  * parameters:
218  * f <-- pointer to field structure
219  * have_flux_bc <-- if true, flux BC coefficients (af and bf) are added
220  * have_mom_bc <-- if true, div BC coefficients (ad and bd) are added
221  * have_conv_bc <-- if true, convection BC coefficients (ac and bc) are added
222  *----------------------------------------------------------------------------*/
223 
224 void
226  bool have_flux_bc,
227  bool have_mom_bc,
228  bool have_conv_bc);
229 
230 /*----------------------------------------------------------------------------*/
231 /* Initialize boundary condition coefficients arrays.
232  *
233  * For fields on location CS_MESH_LOCATION_CELLS, boundary conditions
234  * are located on CS_MESH_LOCATION_BOUNDARY_FACES.
235  *
236  * Boundary condition coefficients are not currently supported for other
237  * locations (though support could be added by mapping a boundary->location
238  * indirection array in the cs_mesh_location_t structure).
239  *
240  * For multidimensional fields, arrays are assumed to have the same
241  * interleaving behavior as the field, unless components are coupled.
242  *
243  * For multidimensional fields with coupled components, interleaving
244  * is the norm, and implicit b and bf coefficient arrays are arrays of
245  * block matrices, not vectors, so the number of entries for each boundary
246  * face is dim*dim instead of dim.
247  *
248  * parameters:
249  * f <-> pointer to field structure
250  * have_flux_bc <-- if true, flux bc coefficients (af and bf)
251  * are initialized
252  * have_mom_bc <-- if true, div BC coefficients (ad and bd)
253  * are initialized
254  * have_conv_bc <-- if true, convection BC coefficients (ac and bc)
255  * are initialized
256  *----------------------------------------------------------------------------*/
257 
258 void
260  bool have_flux_bc,
261  bool have_mom_bc,
262  bool have_conv_bc);
263 
264 /*----------------------------------------------------------------------------
265  * Map existing field boundary condition coefficient arrays.
266  *
267  * For fields on location CS_MESH_LOCATION_CELLS, boundary conditions
268  * are located on CS_MESH_LOCATION_BOUNDARY_FACES.
269  *
270  * Boundary condition coefficients are not currently supported for other
271  * locations (though support could be added by mapping a boundary->location
272  * indirection array in the cs_mesh_location_t structure).
273  *
274  * For multidimensional fields, arrays are assumed to have the same
275  * interleaving behavior as the field, unless components are coupled.
276  *
277  * For multidimensional fields with coupled components, interleaving
278  * is the norm, and implicit coefficients arrays are arrays of block matrices,
279  * not vectors, so the number of entris for each boundary face is
280  * dim*dim instead of dim.
281  *
282  * parameters:
283  * f <-> pointer to field structure
284  * a <-- explicit BC coefficients array
285  * b <-- implicit BC coefficients array
286  * af <-- explicit flux BC coefficients array, or NULL
287  * bf <-- implicit flux BC coefficients array, or NULL
288  * ad explicit div BC coefficients array, or NULL
289  * bd implicit div BC coefficients array, or NULL
290  * ac explicit convection BC coefficients array, or NULL
291  * bc implicit convection BC coefficients array, or NULL
292  *----------------------------------------------------------------------------*/
293 
294 void
296  cs_real_t *a,
297  cs_real_t *b,
298  cs_real_t *af,
299  cs_real_t *bf,
300  cs_real_t *ad,
301  cs_real_t *bd,
302  cs_real_t *ac,
303  cs_real_t *bc);
304 
305 /*----------------------------------------------------------------------------
306  * Copy current field values to previous values if applicable.
307  *
308  * For fields with only one time value, or values not allocated yet,
309  * this is a no-op.
310  *
311  * parameters:
312  * f <-> pointer to field structure
313  *----------------------------------------------------------------------------*/
314 
315 void
317 
318 /*----------------------------------------------------------------------------
319  * Destroy all defined fields.
320  *----------------------------------------------------------------------------*/
321 
322 void
324 
325 /*----------------------------------------------------------------------------
326  * Allocate arrays for all defined fields based on their location.
327  *
328  * Location sized must thus be known.
329  *
330  * Fields that do not own their data should all have been mapped at this
331  * stage, and are checked.
332  *----------------------------------------------------------------------------*/
333 
334 void
336 
337 /*----------------------------------------------------------------------------
338  * Return a pointer to a field based on its id.
339  *
340  * This function requires that a field of the given id is defined.
341  *
342  * parameters:
343  * id <-- field id
344  *
345  * returns:
346  * pointer to the field structure
347  *----------------------------------------------------------------------------*/
348 
349 cs_field_t *
350 cs_field_by_id(int id);
351 
352 /*----------------------------------------------------------------------------
353  * Return a pointer to a field based on its name.
354  *
355  * This function requires that a field of the given name is defined.
356  *
357  * parameters:
358  * name <-- field name
359  *
360  * returns:
361  * pointer to the field structure
362  *----------------------------------------------------------------------------*/
363 
364 cs_field_t *
365 cs_field_by_name(const char *name);
366 
367 /*----------------------------------------------------------------------------
368  * Return a pointer to a field based on its name if present.
369  *
370  * If no field of the given name is defined, NULL is returned.
371  *
372  * parameters:
373  * name <-- field name
374  *
375  * returns:
376  * pointer to the field structure, or NULL
377  *----------------------------------------------------------------------------*/
378 
379 cs_field_t *
380 cs_field_by_name_try(const char *name);
381 
382 /*----------------------------------------------------------------------------
383  * Return the id of a defined field based on its name.
384  *
385  * If no field with the given name exists, -1 is returned.
386  *
387  * parameters:
388  * name <-- field name
389  *
390  * returns:
391  * id the field, or -1 if not found
392  *----------------------------------------------------------------------------*/
393 
394 int
395 cs_field_id_by_name(const char *name);
396 
397 /*----------------------------------------------------------------------------
398  * Return an id associated with a given key name.
399  *
400  * The key must have been defined previously.
401  *
402  * parameters:
403  * name <-- key name
404  *
405  * returns:
406  * id associated with key
407  *----------------------------------------------------------------------------*/
408 
409 int
410 cs_field_key_id(const char *name);
411 
412 /*----------------------------------------------------------------------------
413  * Return an id associated with a given key name if present.
414  *
415  * If the key has not been defined previously, -1 is returned.
416  *
417  * parameters:
418  * name <-- key name
419  *
420  * returns:
421  * id associated with key, or -1
422  *----------------------------------------------------------------------------*/
423 
424 int
425 cs_field_key_id_try(const char *name);
426 
427 /*----------------------------------------------------------------------------
428  * Define a key for an integer value by its name and return an associated id.
429  *
430  * If the key has already been defined, its previous default value is replaced
431  * by the current value, and its id is returned.
432  *
433  * parameters:
434  * name <-- key name
435  * default_value <-- default value associated with key
436  * type flag <-- mask associated with field types with which the
437  * key may be associated, or 0
438  *
439  * returns:
440  * id associated with key
441  *----------------------------------------------------------------------------*/
442 
443 int
444 cs_field_define_key_int(const char *name,
445  int default_value,
446  int type_flag);
447 
448 /*----------------------------------------------------------------------------
449  * Define a key for an floating point value by its name and return an
450  * associated id.
451  *
452  * If the key has already been defined, its previous default value is replaced
453  * by the current value, and its id is returned.
454  *
455  * parameters:
456  * name <-- key name
457  * default_value <-- default value associated with key
458  * type flag <-- mask associated with field types with which the
459  * key may be associated, or 0
460  *
461  * returns:
462  * id associated with key
463  *----------------------------------------------------------------------------*/
464 
465 int
466 cs_field_define_key_double(const char *name,
467  double default_value,
468  int type_flag);
469 
470 /*----------------------------------------------------------------------------
471  * Define a key for an string point value by its name and return an
472  * associated id.
473  *
474  * If the key has already been defined, its previous default value is replaced
475  * by the current value, and its id is returned.
476  *
477  * parameters:
478  * name <-- key name
479  * default_value <-- default value associated with key
480  * type flag <-- mask associated with field types with which the
481  * key may be associated, or 0
482  *
483  * returns:
484  * id associated with key
485  *----------------------------------------------------------------------------*/
486 
487 int
488 cs_field_define_key_str(const char *name,
489  const char *default_value,
490  int type_flag);
491 
492 /*----------------------------------------------------------------------------
493  * Define a key for a structure value by its name and return an
494  * associated id.
495  *
496  * If the key has already been defined, its previous default value is replaced
497  * by the current value, and its id is returned.
498  *
499  * parameters:
500  * name <-- key name
501  * default_value <-- pointer to default value associated with key
502  * log_funct <-- pointer to logging function
503  * size <-- sizeof structure
504  * type_flag <-- mask associated with field types with which
505  * the key may be associated, or 0
506  *
507  * returns:
508  * id associated with key
509  *----------------------------------------------------------------------------*/
510 
511 int
512 cs_field_define_key_struct(const char *name,
513  const void *default_value,
514  cs_field_log_key_struct_t *log_func,
515  size_t size,
516  int type_flag);
517 
518 /*----------------------------------------------------------------------------
519  * Define a sub key.
520  *
521  * The sub key is the same type as the parent key.
522  *
523  * For a given field, when querying a sub key's value and that value has not
524  * been set, the query will return the value of the parent key.
525  *
526  * parameters:
527  * name <-- key name
528  * parent_id <-- parent key id
529  *
530  * returns:
531  * id associated with key
532  *----------------------------------------------------------------------------*/
533 
534 int
535 cs_field_define_sub_key(const char *name,
536  int parent_id);
537 
538 /*----------------------------------------------------------------------------
539  * Destroy all defined field keys and associated values.
540  *----------------------------------------------------------------------------*/
541 
542 void
544 
545 /*----------------------------------------------------------------------------
546  * Get the type flag associated with a given key id.
547  *
548  * If the key has not been defined previously, -1 is returned.
549  *
550  * parameters:
551  * key_id <-- id of associated key
552  *
553  * returns:
554  * type flag associated with key, or -1
555  *----------------------------------------------------------------------------*/
556 
557 int
558 cs_field_key_flag(int key_id);
559 
560 /*----------------------------------------------------------------------------
561  * Query if a given key has been set for a field.
562  *
563  * If the key id is not valid, or the field category is not
564  * compatible, a fatal error is provoked.
565  *
566  * parameters:
567  * f <-- pointer to field structure
568  * key_id <-- id of associated key
569  *
570  * returns:
571  * true if the key has been set for this field, false otherwise
572  *----------------------------------------------------------------------------*/
573 
574 bool
576  int key_id);
577 
578 /*----------------------------------------------------------------------------
579  * Assign a integer value for a given key to a field.
580  *
581  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
582  * If the field category is not compatible with the key (as defined
583  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
584  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
585  *
586  * parameters:
587  * f <-- pointer to field structure
588  * key_id <-- id of associated key
589  * value <-- value associated with key
590  *
591  * returns:
592  * 0 in case of success, > 1 in case of error
593  *----------------------------------------------------------------------------*/
594 
595 int
597  int key_id,
598  int value);
599 
600 /*----------------------------------------------------------------------------
601  * Return a integer value for a given key associated with a field.
602  *
603  * If the key id is not valid, or the value type or field category is not
604  * compatible, a fatal error is provoked.
605  *
606  * parameters:
607  * f <-- pointer to field structure
608  * key_id <-- id of associated key
609  *
610  * returns:
611  * integer value associated with the key id for this field
612  *----------------------------------------------------------------------------*/
613 
614 int
616  int key_id);
617 
618 /*----------------------------------------------------------------------------
619  * Assign a floating point value for a given key to a field.
620  *
621  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
622  * If the field category is not compatible with the key (as defined
623  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
624  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
625  *
626  * parameters:
627  * f <-- pointer to field structure
628  * key_id <-- id of associated key
629  * value <-- value associated with key
630  *
631  * returns:
632  * 0 in case of success, > 1 in case of error
633  *----------------------------------------------------------------------------*/
634 
635 int
637  int key_id,
638  double value);
639 
640 /*----------------------------------------------------------------------------
641  * Return a floating point value for a given key associated with a field.
642  *
643  * If the key id is not valid, or the value type or field category is not
644  * compatible, a fatal error is provoked.
645  *
646  * parameters:
647  * f <-- pointer to field structure
648  * key_id <-- id of associated key
649  *
650  * returns:
651  * floating point value associated with the key id for this field
652  *----------------------------------------------------------------------------*/
653 
654 double
656  int key_id);
657 
658 /*----------------------------------------------------------------------------
659  * Assign a character string value for a given key to a field.
660  *
661  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
662  * If the field category is not compatible with the key (as defined
663  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
664  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
665  *
666  * parameters:
667  * f <-- pointer to field structure
668  * key_id <-- id of associated key
669  * str <-- string associated with key
670  *
671  * returns:
672  * 0 in case of success, > 1 in case of error
673  *----------------------------------------------------------------------------*/
674 
675 int
677  int key_id,
678  const char *str);
679 
680 /*----------------------------------------------------------------------------
681  * Return a string for a given key associated with a field.
682  *
683  * If the key id is not valid, or the value type or field category is not
684  * compatible, a fatal error is provoked.
685  *
686  * parameters:
687  * f <-- pointer to field structure
688  * key_id <-- id of associated key
689  *
690  * returns:
691  * pointer to character string associated with the key id for this field
692  *----------------------------------------------------------------------------*/
693 
694 const char *
696  int key_id);
697 
698 
699 /*----------------------------------------------------------------------------
700  * Assign a simple structure for a given key to a field.
701  *
702  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
703  * If the field category is not compatible with the key (as defined
704  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
705  *
706  * parameters:
707  * f <-- pointer to field structure
708  * key_id <-- id of associated key
709  * s <-- structure associated with key
710  *
711  * returns:
712  * 0 in case of success, > 1 in case of error
713  *----------------------------------------------------------------------------*/
714 
715 int
717  int key_id,
718  void *s);
719 
720 /*----------------------------------------------------------------------------
721  * Return a structure for a given key associated with a field.
722  *
723  * If the key id is not valid, or the value type or field category is not
724  * compatible, a fatal error is provoked.
725  *
726  * parameters:
727  * f <-- pointer to field structure
728  * key_id <-- id of associated key
729  * s <-- structure associated with key
730  *
731  * returns:
732  * pointer to structure associated with the key id for this field
733  * (same as s)
734  *----------------------------------------------------------------------------*/
735 
736 const void *
738  int key_id,
739  void *s);
740 
741 /*----------------------------------------------------------------------------
742  * Print info relative to all field definitions to log file.
743  *----------------------------------------------------------------------------*/
744 
745 void
746 cs_field_log_defs(void);
747 
748 /*----------------------------------------------------------------------------
749  * Print info relative to a given field to log file.
750  *
751  * parameters:
752  * f <-- pointer to field structure
753  * log_keywords <-- log level for keywords (0: do not log,
754  * 1: log non-default values, 2: log all)
755  *----------------------------------------------------------------------------*/
756 
757 void
759  int log_keywords);
760 
761 /*----------------------------------------------------------------------------
762  * Print info relative to all defined fields to log file.
763  *
764  * parameters:
765  * log_keywords <-- log level for keywords (0: do not log,
766  * 1: log non-default values, 2: log all)
767  *----------------------------------------------------------------------------*/
768 
769 void
770 cs_field_log_fields(int log_keywords);
771 
772 /*----------------------------------------------------------------------------
773  * Print info relative to all key definitions to log file.
774  *----------------------------------------------------------------------------*/
775 
776 void
778 
779 /*----------------------------------------------------------------------------
780  * Print info relative to a given field key to log file.
781  *
782  * parameters:
783  * int key_id <-- id of associated key
784  * log_defaults <-- if true, log default field values in addition to
785  * defined field values
786  *----------------------------------------------------------------------------*/
787 
788 void
789 cs_field_log_key_vals(int key_id,
790  bool log_defaults);
791 
792 /*----------------------------------------------------------------------------
793  * Print info relative to all given field keys to log file.
794  *
795  * parameters:
796  * log_defaults <-- if true, log default field values in addition to
797  * defined field values
798  *----------------------------------------------------------------------------*/
799 
800 void
801 cs_field_log_all_key_vals(bool log_defaults);
802 
803 /*----------------------------------------------------------------------------
804  * Define base keys.
805  *
806  * Keys defined by this function are:
807  * "label" (string)
808  * "log" (integer)
809  * "post_vis" (integer)
810  * "post_probes" (integer)
811  * "coupled" (integer, restricted to CS_FIELD_VARIABLE)
812  * "moment_dt" (integer, restricted to CS_FIELD_PROPERTY);
813  *
814  * A recommened practice for different submodules would be to use
815  * "cs_<module>_key_init() functions to define keys specific to those modules.
816  *----------------------------------------------------------------------------*/
817 
818 void
820 
821 /*----------------------------------------------------------------------------*/
822 
824 
825 #endif /* __CS_FIELD_H__ */