8.1
general documentation
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-2023 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 
50 /*
51  * Field property type
52  */
53 
55 #define CS_FIELD_INTENSIVE (1 << 0)
56 
58 #define CS_FIELD_EXTENSIVE (1 << 1)
59 
60 /* Field category */
61 
63 #define CS_FIELD_VARIABLE (1 << 2)
64 
66 #define CS_FIELD_PROPERTY (1 << 3)
67 
69 #define CS_FIELD_POSTPROCESS (1 << 4)
70 
72 #define CS_FIELD_ACCUMULATOR (1 << 5)
73 
75 #define CS_FIELD_USER (1 << 6)
76 
78 #define CS_FIELD_CDO (1 << 7)
79 
82 /*============================================================================
83  * Type definitions
84  *============================================================================*/
85 
86 /* Field handling error types */
87 /*----------------------------*/
88 
89 typedef enum {
90 
98 
100 
102 /*------------------------------------------------------*/
103 
104 typedef struct {
105 
106  int location_id; /* Id of matching location */
107 
108  int *icodcl; /* low-level BC type code */
109  cs_real_t *rcodcl1; /* 1st component of low-level BC */
110  cs_real_t *rcodcl2; /* 2nd component of low-level BC */
111  cs_real_t *rcodcl3; /* 3rd component of low-level BC */
112 
113  cs_real_t *a; /* Explicit coefficient */
114  cs_real_t *b; /* Implicit coefficient */
115  cs_real_t *af; /* Explicit coefficient for flux */
116  cs_real_t *bf; /* Implicit coefficient for flux */
117  cs_real_t *ad; /* Explicit coefficient for divergence */
118  cs_real_t *bd; /* Implicit coefficient for divergence */
119  cs_real_t *ac; /* Explicit coefficient for convection */
120  cs_real_t *bc; /* Implicit coefficient for convection */
121 
122  cs_real_t *hint; /* coefficient for internal coupling */
123  cs_real_t *_hext; /* coefficient for internal coupling
124  (maps to rcodcl2 when present) */
125 
127 
128 /* Field descriptor */
129 /*------------------*/
130 
131 typedef struct {
132 
133  const char *name; /* Canonical name */
134 
135  int id; /* Field id */
136  int type; /* Field type flag */
137 
138  int dim; /* Field dimension */
139 
140  int location_id; /* Id of matching location */
141 
142  int n_time_vals; /* Number of time values */
143 
144  cs_real_t **vals; /* For each active location, pointer
145  to matching values arrays
146  vals[0][:] = val
147  vals[1][:] = val_pre
148  vals[p][:] = p ith previous field
149  p < n_time_vals */
150 
151 
152  cs_real_t *val; /* For each active location, pointer
153  to matching values array */
154 
155  cs_real_t *val_pre; /* For each active location, pointer
156  to matching previous values array
157  (if n_time_vals == 2) */
158 
159  cs_real_t *grad; /* For each active location, pointer
160  to matching gradient array for
161  variable type fields */
162 
163  cs_field_bc_coeffs_t *bc_coeffs; /* Boundary condition coefficients,
164  for variable type fields */
165 
166  bool is_owner; /* Ownership flag for values */
167 
168 } cs_field_t;
169 
170 /*----------------------------------------------------------------------------
171  * Function pointer for structure associated to field key
172  *
173  * parameters:
174  * t <-- pointer to structure
175  *----------------------------------------------------------------------------*/
176 
177 typedef void
178 (cs_field_log_key_struct_t) (const void *t);
179 
180 /*----------------------------------------------------------------------------
181  * Function pointer for structure associated to field key
182  *
183  * parameters:
184  * t <-- pointer to structure
185  *----------------------------------------------------------------------------*/
186 
187 typedef void
189 
190 /*============================================================================
191  * Global variables
192  *============================================================================*/
193 
194 /* Names for components */
195 
196 extern const char *cs_glob_field_comp_name_3[];
197 extern const char *cs_glob_field_comp_name_6[];
198 extern const char *cs_glob_field_comp_name_9[];
199 
200 /*=============================================================================
201  * Public function prototypes
202  *============================================================================*/
203 
204 /*----------------------------------------------------------------------------
205  * Return the number of defined fields.
206  *
207  * returns:
208  * number of defined fields.
209  *----------------------------------------------------------------------------*/
210 
211 int
212 cs_field_n_fields(void);
213 
214 /*----------------------------------------------------------------------------
215  * Create a field descriptor.
216  *
217  * parameters:
218  * name <-- field name
219  * type_flag <-- mask of field property and category values
220  * location_id <-- id of associated location
221  * dim <-- field dimension (number of components)
222  * has_previous <-- maintain values at the previous time step ?
223  *
224  * returns:
225  * pointer to new field.
226  *----------------------------------------------------------------------------*/
227 
228 cs_field_t *
229 cs_field_create(const char *name,
230  int type_flag,
231  int location_id,
232  int dim,
233  bool has_previous);
234 
235 /*----------------------------------------------------------------------------*/
254 /*----------------------------------------------------------------------------*/
255 
256 cs_field_t *
257 cs_field_find_or_create(const char *name,
258  int type_flag,
259  int location_id,
260  int dim,
261  bool has_previous);
262 
263 /*----------------------------------------------------------------------------
264  * Change the number of time values managed by a field.
265  *
266  * The minimum will never be below 1, as the current time is always handled.
267  *
268  * parameters:
269  * f <-> pointer to field structure
270  * n_time_vals <-- number of time values to maintain
271  *----------------------------------------------------------------------------*/
272 
273 void
275  int n_time_vals);
276 
277 /*----------------------------------------------------------------------------
278  * Allocate arrays for field values.
279  *
280  * parameters:
281  * f <-- pointer to field structure
282  *----------------------------------------------------------------------------*/
283 
284 void
286 
287 /*----------------------------------------------------------------------------
288  * Map existing value arrays to field descriptor.
289  *
290  * parameters:
291  * f <-> pointer to field structure
292  * val <-- pointer to array of values
293  * val_pre <-- pointer to array of previous values, or NULL
294  *----------------------------------------------------------------------------*/
295 
296 void
298  cs_real_t *val,
299  cs_real_t *val_pre);
300 
301 /*----------------------------------------------------------------------------
302  * Allocate boundary condition coefficient arrays.
303  *
304  * For fields on location CS_MESH_LOCATION_CELLS, boundary conditions
305  * are located on CS_MESH_LOCATION_BOUNDARY_FACES.
306  *
307  * Boundary condition coefficients are not currently supported for other
308  * locations (though support could be added by mapping a boundary->location
309  * indirection array in the cs_mesh_location_t structure).
310  *
311  * For multidimensional fields with coupled components, implicit b and bf
312  * coefficient arrays are arrays of block matrices, not vectors, so the
313  * number of entries for each boundary face is dim*dim instead of dim.
314  *
315  * parameters:
316  * f <-- pointer to field structure
317  * have_flux_bc <-- if true, flux BC coefficients (af and bf) are added
318  * have_mom_bc <-- if true, div BC coefficients (ad and bd) are added
319  * have_conv_bc <-- if true, convection BC coefficients (ac and bc) are added
320  * have_exch_bc <-- if true, exchange boundary coefficients (hint and hext)
321  * are added
322  *----------------------------------------------------------------------------*/
323 
324 void
326  bool have_flux_bc,
327  bool have_mom_bc,
328  bool have_conv_bc,
329  bool have_exch_bc);
330 
331 /*----------------------------------------------------------------------------*/
332 /* Initialize boundary condition coefficients arrays.
333  *
334  * For fields on location CS_MESH_LOCATION_CELLS, boundary conditions
335  * are located on CS_MESH_LOCATION_BOUNDARY_FACES.
336  *
337  * Boundary condition coefficients are not currently supported for other
338  * locations (though support could be added by mapping a boundary->location
339  * indirection array in the cs_mesh_location_t structure).
340  *
341  * For multidimensional fields with coupled components, implicit b and bf
342  * coefficient arrays are arrays of block matrices, not vectors, so the
343  * number of entries for each boundary face is dim*dim instead of dim.
344  *
345  * parameters:
346  * f <-> pointer to field structure
347  *----------------------------------------------------------------------------*/
348 
349 void
351 
352 /*----------------------------------------------------------------------------
353  * Allocate arrays for field gradient.
354  *
355  * parameters:
356  * f <-- pointer to field structure
357  *----------------------------------------------------------------------------*/
358 
359 void
361 
362 /*----------------------------------------------------------------------------
363  * Set current field values to the given constant.
364  *
365  * parameters:
366  * f <-> pointer to field structure
367  * c <-- assigned value
368  *----------------------------------------------------------------------------*/
369 
370 void
372  cs_real_t c);
373 
374 /*----------------------------------------------------------------------------
375  * Copy current field values to previous values if applicable.
376  *
377  * For fields with only one time value, or values not allocated yet,
378  * this is a no-op.
379  *
380  * parameters:
381  * f <-> pointer to field structure
382  *----------------------------------------------------------------------------*/
383 
384 void
386 
387 /*----------------------------------------------------------------------------
388  * Destroy all defined fields.
389  *----------------------------------------------------------------------------*/
390 
391 void
393 
394 /*----------------------------------------------------------------------------
395  * Allocate arrays for all defined fields based on their location.
396  *
397  * Location sized must thus be known.
398  *
399  * Fields that do not own their data should all have been mapped at this
400  * stage, and are checked.
401  *----------------------------------------------------------------------------*/
402 
403 void
405 
406 /*----------------------------------------------------------------------------
407  * Return a pointer to a field based on its id.
408  *
409  * This function requires that a field of the given id is defined.
410  *
411  * parameters:
412  * id <-- field id
413  *
414  * returns:
415  * pointer to the field structure
416  *----------------------------------------------------------------------------*/
417 
418 cs_field_t *
419 cs_field_by_id(int id);
420 
421 /*----------------------------------------------------------------------------
422  * Return a pointer to a field based on its name.
423  *
424  * This function requires that a field of the given name is defined.
425  *
426  * parameters:
427  * name <-- field name
428  *
429  * returns:
430  * pointer to the field structure
431  *----------------------------------------------------------------------------*/
432 
433 cs_field_t *
434 cs_field_by_name(const char *name);
435 
436 /*----------------------------------------------------------------------------
437  * Return a pointer to a field based on its name if present.
438  *
439  * If no field of the given name is defined, NULL is returned.
440  *
441  * parameters:
442  * name <-- field name
443  *
444  * returns:
445  * pointer to the field structure, or NULL
446  *----------------------------------------------------------------------------*/
447 
448 cs_field_t *
449 cs_field_by_name_try(const char *name);
450 
451 /*----------------------------------------------------------------------------*/
462 /*----------------------------------------------------------------------------*/
463 
464 cs_field_t *
465 cs_field_by_composite_name(const char *name_prefix,
466  const char *name_suffix);
467 
468 /*----------------------------------------------------------------------------*/
480 /*----------------------------------------------------------------------------*/
481 
482 cs_field_t *
483 cs_field_by_composite_name_try(const char *name_prefix,
484  const char *name_suffix);
485 
486 /*----------------------------------------------------------------------------
487  * Return the id of a defined field based on its name.
488  *
489  * If no field with the given name exists, -1 is returned.
490  *
491  * parameters:
492  * name <-- field name
493  *
494  * returns:
495  * id the field, or -1 if not found
496  *----------------------------------------------------------------------------*/
497 
498 int
499 cs_field_id_by_name(const char *name);
500 
501 /*----------------------------------------------------------------------------
502  * Return the id of a defined field and an associated component
503  * based on a component name.
504  *
505  * If no field with the given name exists, -1 is returned.
506  *
507  * parameters:
508  * name <-- field or field+component name
509  * f_id --> field id, or -1 if no match was found
510  * c_id --> component id, or -1 for all components
511  *----------------------------------------------------------------------------*/
512 
513 void
514 cs_field_component_id_by_name(const char *name,
515  int *f_id,
516  int *c_id);
517 
518 /*----------------------------------------------------------------------------
519  * Return an id associated with a given key name.
520  *
521  * The key must have been defined previously.
522  *
523  * parameters:
524  * name <-- key name
525  *
526  * returns:
527  * id associated with key
528  *----------------------------------------------------------------------------*/
529 
530 int
531 cs_field_key_id(const char *name);
532 
533 /*----------------------------------------------------------------------------
534  * Return an id associated with a given key name if present.
535  *
536  * If the key has not been defined previously, -1 is returned.
537  *
538  * parameters:
539  * name <-- key name
540  *
541  * returns:
542  * id associated with key, or -1
543  *----------------------------------------------------------------------------*/
544 
545 int
546 cs_field_key_id_try(const char *name);
547 
548 /*----------------------------------------------------------------------------
549  * Define a key for an integer value by its name and return an associated id.
550  *
551  * If the key has already been defined, its previous default value is replaced
552  * by the current value, and its id is returned.
553  *
554  * parameters:
555  * name <-- key name
556  * default_value <-- default value associated with key
557  * type flag <-- mask associated with field types with which the
558  * key may be associated, or 0
559  *
560  * returns:
561  * id associated with key
562  *----------------------------------------------------------------------------*/
563 
564 int
565 cs_field_define_key_int(const char *name,
566  int default_value,
567  int type_flag);
568 
569 /*----------------------------------------------------------------------------
570  * Define a key for an floating point value by its name and return an
571  * associated id.
572  *
573  * If the key has already been defined, its previous default value is replaced
574  * by the current value, and its id is returned.
575  *
576  * parameters:
577  * name <-- key name
578  * default_value <-- default value associated with key
579  * type flag <-- mask associated with field types with which the
580  * key may be associated, or 0
581  *
582  * returns:
583  * id associated with key
584  *----------------------------------------------------------------------------*/
585 
586 int
587 cs_field_define_key_double(const char *name,
588  double default_value,
589  int type_flag);
590 
591 /*----------------------------------------------------------------------------
592  * Define a key for an string point value by its name and return an
593  * associated id.
594  *
595  * If the key has already been defined, its previous default value is replaced
596  * by the current value, and its id is returned.
597  *
598  * parameters:
599  * name <-- key name
600  * default_value <-- default value associated with key
601  * type flag <-- mask associated with field types with which the
602  * key may be associated, or 0
603  *
604  * returns:
605  * id associated with key
606  *----------------------------------------------------------------------------*/
607 
608 int
609 cs_field_define_key_str(const char *name,
610  const char *default_value,
611  int type_flag);
612 
613 /*----------------------------------------------------------------------------
614  * Define a key for a structure value by its name and return an
615  * associated id.
616  *
617  * If the key has already been defined, its previous default value is replaced
618  * by the current value, and its id is returned.
619  *
620  * parameters:
621  * name <-- key name
622  * default_value <-- pointer to default value associated with key
623  * log_funct <-- pointer to logging function
624  * log_func_default <-- pointer to default logging function
625  * clear_func <-- pointer to substructures free function
626  * size <-- sizeof structure
627  * type_flag <-- mask associated with field types with which
628  * the key may be associated, or 0
629  *
630  * returns:
631  * id associated with key
632  *----------------------------------------------------------------------------*/
633 
634 int
635 cs_field_define_key_struct(const char *name,
636  const void *default_value,
637  cs_field_log_key_struct_t *log_func,
638  cs_field_log_key_struct_t *log_func_default,
639  cs_field_clear_key_struct_t *clear_func,
640  size_t size,
641  int type_flag);
642 
643 /*----------------------------------------------------------------------------
644  * Define a sub key.
645  *
646  * The sub key is the same type as the parent key.
647  *
648  * For a given field, when querying a sub key's value and that value has not
649  * been set, the query will return the value of the parent key.
650  *
651  * parameters:
652  * name <-- key name
653  * parent_id <-- parent key id
654  *
655  * returns:
656  * id associated with key
657  *----------------------------------------------------------------------------*/
658 
659 int
660 cs_field_define_sub_key(const char *name,
661  int parent_id);
662 
663 /*----------------------------------------------------------------------------
664  * Destroy all defined field keys and associated values.
665  *----------------------------------------------------------------------------*/
666 
667 void
669 
670 /*----------------------------------------------------------------------------
671  * Get the type flag associated with a given key id.
672  *
673  * If the key has not been defined previously, -1 is returned.
674  *
675  * parameters:
676  * key_id <-- id of associated key
677  *
678  * returns:
679  * type flag associated with key, or -1
680  *----------------------------------------------------------------------------*/
681 
682 int
683 cs_field_key_flag(int key_id);
684 
685 /*----------------------------------------------------------------------------
686  * Disable logging setup values associated with a given key.
687  *
688  * This is useful when a key is used not for setup purposes, but to track
689  * values associated with a field, such as convergence or performance data.
690  *
691  * parameters:
692  * key_id <-- id of associated key
693  *----------------------------------------------------------------------------*/
694 
695 void
697 
698 /*----------------------------------------------------------------------------
699  * Query if a given key has been set for a field.
700  *
701  * If the key id is not valid, or the field category is not
702  * compatible, a fatal error is provoked.
703  *
704  * parameters:
705  * f <-- pointer to field structure
706  * key_id <-- id of associated key
707  *
708  * returns:
709  * true if the key has been set for this field, false otherwise
710  *----------------------------------------------------------------------------*/
711 
712 bool
714  int key_id);
715 
716 /*----------------------------------------------------------------------------
717  * Query if a given key has been locked for a field.
718  *
719  * If the key id is not valid, or the field category is not
720  * compatible, a fatal error is provoked.
721  *
722  * parameters:
723  * f <-- pointer to field structure
724  * key_id <-- id of associated key
725  *
726  * returns:
727  * true if the key has been locked for this field, false otherwise
728  *----------------------------------------------------------------------------*/
729 
730 bool
732  int key_id);
733 
734 /*----------------------------------------------------------------------------
735  * Lock a field relative to a given key.
736  *
737  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
738  * If the field category is not compatible with the key (as defined
739  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
740  *
741  * parameters:
742  * f <-- pointer to field structure
743  * key_id <-- id of associated key
744  * value <-- value associated with key
745  *
746  * returns:
747  * 0 in case of success, > 1 in case of error
748  *----------------------------------------------------------------------------*/
749 
750 int
752  int key_id);
753 
754 /*----------------------------------------------------------------------------
755  * Assign a integer value for a given key to a field.
756  *
757  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
758  * If the field category is not compatible with the key (as defined
759  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
760  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
761  * If the key value has been locked, CS_FIELD_LOCKED is returned.
762  *
763  * parameters:
764  * f <-- pointer to field structure
765  * key_id <-- id of associated key
766  * value <-- value associated with key
767  *
768  * returns:
769  * 0 in case of success, > 1 in case of error
770  *----------------------------------------------------------------------------*/
771 
772 int
774  int key_id,
775  int value);
776 
777 /*----------------------------------------------------------------------------
778  * Return a integer value for a given key associated with a field.
779  *
780  * If the key id is not valid, or the value type or field category is not
781  * compatible, a fatal error is provoked.
782  *
783  * parameters:
784  * f <-- pointer to field structure
785  * key_id <-- id of associated key
786  *
787  * returns:
788  * integer value associated with the key id for this field
789  *----------------------------------------------------------------------------*/
790 
791 int
793  int key_id);
794 
795 /*----------------------------------------------------------------------------
796  * Set integer bits matching a mask to 1 for a given key for a field.
797  *
798  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
799  * If the field category is not compatible with the key (as defined
800  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
801  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
802  * If the key value has been locked, CS_FIELD_LOCKED is returned.
803  *
804  * parameters:
805  * f <-- pointer to field structure
806  * key_id <-- id of associated key
807  * mask <-- mask associated with key
808  *
809  * returns:
810  * 0 in case of success, > 1 in case of error
811  *----------------------------------------------------------------------------*/
812 
813 int
815  int key_id,
816  int mask);
817 
818 /*----------------------------------------------------------------------------
819  * Set integer bits matching a mask to 0 for a given key for a field.
820  *
821  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
822  * If the field category is not compatible with the key (as defined
823  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
824  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
825  * If the key value has been locked, CS_FIELD_LOCKED is returned.
826  *
827  * parameters:
828  * f <-- pointer to field structure
829  * key_id <-- id of associated key
830  * mask <-- mask associated with key
831  *
832  * returns:
833  * 0 in case of success, > 1 in case of error
834  *----------------------------------------------------------------------------*/
835 
836 int
838  int key_id,
839  int mask);
840 
841 /*----------------------------------------------------------------------------
842  * Assign a floating point value for a given key to a field.
843  *
844  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
845  * If the field category is not compatible with the key (as defined
846  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
847  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
848  * If the key value has been locked, CS_FIELD_LOCKED is returned.
849  *
850  * parameters:
851  * f <-- pointer to field structure
852  * key_id <-- id of associated key
853  * value <-- value associated with key
854  *
855  * returns:
856  * 0 in case of success, > 1 in case of error
857  *----------------------------------------------------------------------------*/
858 
859 int
861  int key_id,
862  double value);
863 
864 /*----------------------------------------------------------------------------
865  * Return a floating point value for a given key associated with a field.
866  *
867  * If the key id is not valid, or the value type or field category is not
868  * compatible, a fatal error is provoked.
869  *
870  * parameters:
871  * f <-- pointer to field structure
872  * key_id <-- id of associated key
873  *
874  * returns:
875  * floating point value associated with the key id for this field
876  *----------------------------------------------------------------------------*/
877 
878 double
880  int key_id);
881 
882 /*----------------------------------------------------------------------------
883  * Assign a character string value for a given key to a field.
884  *
885  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
886  * If the field category is not compatible with the key (as defined
887  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
888  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
889  * If the key value has been locked, CS_FIELD_LOCKED is returned.
890  *
891  * parameters:
892  * f <-- pointer to field structure
893  * key_id <-- id of associated key
894  * str <-- string associated with key
895  *
896  * returns:
897  * 0 in case of success, > 1 in case of error
898  *----------------------------------------------------------------------------*/
899 
900 int
902  int key_id,
903  const char *str);
904 
905 /*----------------------------------------------------------------------------
906  * Return a string for a given key associated with a field.
907  *
908  * If the key id is not valid, or the value type or field category is not
909  * compatible, a fatal error is provoked.
910  *
911  * parameters:
912  * f <-- pointer to field structure
913  * key_id <-- id of associated key
914  *
915  * returns:
916  * pointer to character string associated with the key id for this field
917  *----------------------------------------------------------------------------*/
918 
919 const char *
921  int key_id);
922 
923 
924 /*----------------------------------------------------------------------------
925  * Assign a simple structure for a given key to a field.
926  *
927  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
928  * If the field category is not compatible with the key (as defined
929  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
930  * If the key value has been locked, CS_FIELD_LOCKED is returned.
931  *
932  * parameters:
933  * f <-- pointer to field structure
934  * key_id <-- id of associated key
935  * s <-- structure associated with key
936  *
937  * returns:
938  * 0 in case of success, > 1 in case of error
939  *----------------------------------------------------------------------------*/
940 
941 int
943  int key_id,
944  void *s);
945 
946 /*----------------------------------------------------------------------------
947  * Return a structure for a given key associated with a field.
948  *
949  * If the key id is not valid, or the value type or field category is not
950  * compatible, a fatal error is provoked.
951  *
952  * parameters:
953  * f <-- pointer to field structure
954  * key_id <-- id of associated key
955  * s <-- structure associated with key
956  *
957  * returns:
958  * pointer to structure associated with the key id for this field
959  * (same as s)
960  *----------------------------------------------------------------------------*/
961 
962 const void *
964  int key_id,
965  void *s);
966 
967 /*----------------------------------------------------------------------------*/
983 /*----------------------------------------------------------------------------*/
984 
985 void *
987  int key_id);
988 
989 /*----------------------------------------------------------------------------*/
1002 /*----------------------------------------------------------------------------*/
1003 
1004 const void *
1006  int key_id);
1007 
1008 /*----------------------------------------------------------------------------
1009  * Print info relative to all field definitions to log file.
1010  *----------------------------------------------------------------------------*/
1011 
1012 void
1013 cs_field_log_defs(void);
1014 
1015 /*----------------------------------------------------------------------------
1016  * Print info relative to a given field to log file.
1017  *
1018  * parameters:
1019  * f <-- pointer to field structure
1020  * log_keywords <-- log level for keywords (0: do not log,
1021  * 1: log non-default values, 2: log all)
1022  *----------------------------------------------------------------------------*/
1023 
1024 void
1025 cs_field_log_info(const cs_field_t *f,
1026  int log_keywords);
1027 
1028 /*----------------------------------------------------------------------------
1029  * Print info relative to all defined fields to log file.
1030  *
1031  * parameters:
1032  * log_keywords <-- log level for keywords (0: do not log,
1033  * 1: log non-default values, 2: log all)
1034  *----------------------------------------------------------------------------*/
1035 
1036 void
1037 cs_field_log_fields(int log_keywords);
1038 
1039 /*----------------------------------------------------------------------------
1040  * Print info relative to all key definitions to log file.
1041  *----------------------------------------------------------------------------*/
1042 
1043 void
1044 cs_field_log_key_defs(void);
1045 
1046 /*----------------------------------------------------------------------------
1047  * Print info relative to a given field key to log file.
1048  *
1049  * parameters:
1050  * int key_id <-- id of associated key
1051  * log_defaults <-- if true, log default field values in addition to
1052  * defined field values
1053  *----------------------------------------------------------------------------*/
1054 
1055 void
1056 cs_field_log_key_vals(int key_id,
1057  bool log_defaults);
1058 
1059 /*----------------------------------------------------------------------------
1060  * Print info relative to all given field keys to log file.
1061  *
1062  * parameters:
1063  * log_defaults <-- if true, log default field values in addition to
1064  * defined field values
1065  *----------------------------------------------------------------------------*/
1066 
1067 void
1068 cs_field_log_all_key_vals(bool log_defaults);
1069 
1070 /*----------------------------------------------------------------------------
1071  * Define base keys.
1072  *
1073  * Keys defined by this function are:
1074  * "label" (string)
1075  * "log" (integer)
1076  * "post_vis" (integer)
1077  * "coupled" (integer, restricted to CS_FIELD_VARIABLE)
1078  * "moment_id" (integer, restricted to
1079  * CS_FIELD_ACCUMULATOR | CS_FIELD_POSTPROCESS);
1080  *
1081  * A recommened practice for different submodules would be to use
1082  * "cs_<module>_key_init() functions to define keys specific to those modules.
1083  *----------------------------------------------------------------------------*/
1084 
1085 void
1087 
1088 /*----------------------------------------------------------------------------
1089  * Return a label associated with a field.
1090  *
1091  * If the "label" key has been set for this field, its associated string
1092  * is returned. Otherwise, the field's name is returned.
1093  *
1094  * parameters:
1095  * f <-- pointer to field structure
1096  *
1097  * returns:
1098  * pointer to character string associated with label for this field
1099  *----------------------------------------------------------------------------*/
1100 
1101 const char *
1102 cs_field_get_label(const cs_field_t *f);
1103 
1104 /*----------------------------------------------------------------------------*/
1105 
1107 
1108 #endif /* __CS_FIELD_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:514
double cs_real_t
Floating-point value.
Definition: cs_defs.h:319
#define END_C_DECLS
Definition: cs_defs.h:515
cs_field_t * cs_field_by_id(int id)
Return a pointer to a field based on its id.
Definition: cs_field.c:2320
const void * cs_field_get_key_struct_const_ptr(const cs_field_t *f, int key_id)
Return a read-only pointer to a simple structure for a given key to a field.
Definition: cs_field.c:3642
const char * cs_field_get_label(const cs_field_t *f)
Return a label associated with a field.
Definition: cs_field.c:4369
const char * cs_field_get_key_str(const cs_field_t *f, int key_id)
Return a string for a given key associated with a field.
Definition: cs_field.c:3370
int cs_field_set_key_int(cs_field_t *f, int key_id, int value)
Assign a integer value for a given key to a field.
Definition: cs_field.c:3020
int cs_field_clear_key_int_bits(cs_field_t *f, int key_id, int mask)
Set integer bits matching a mask to 0 for a given key for a field.
Definition: cs_field.c:3170
void cs_field_init_bc_coeffs(cs_field_t *f)
Initialize boundary condition coefficients arrays.
Definition: cs_field.c:1924
cs_field_t * cs_field_by_composite_name_try(const char *name_prefix, const char *name_suffix)
Return a pointer to a field based on a composite name if present.
Definition: cs_field.c:2422
int cs_field_define_key_int(const char *name, int default_value, int type_flag)
Define a key for an integer value by its name and return an associated id.
Definition: cs_field.c:2629
cs_field_t * cs_field_create(const char *name, int type_flag, int location_id, int dim, bool has_previous)
Create a field descriptor.
Definition: cs_field.c:1522
int cs_field_get_key_int(const cs_field_t *f, int key_id)
Return a integer value for a given key associated with a field.
Definition: cs_field.c:3068
int cs_field_key_flag(int key_id)
Get the type flag associated with a given key id.
Definition: cs_field.c:2866
void cs_field_set_n_time_vals(cs_field_t *f, int n_time_vals)
Change the number of time values managed by a field.
Definition: cs_field.c:1626
cs_field_t * cs_field_by_name_try(const char *name)
Return a pointer to a field based on its name if present.
Definition: cs_field.c:2370
int cs_field_define_key_str(const char *name, const char *default_value, int type_flag)
Define a key for a string value by its name and return an associated id.
Definition: cs_field.c:2703
void cs_field_set_values(cs_field_t *f, cs_real_t c)
Set current field values to the given constant.
Definition: cs_field.c:2143
void cs_field_destroy_all_keys(void)
Destroy all defined field keys and associated values.
Definition: cs_field.c:2834
int cs_field_n_fields(void)
Return the number of defined fields.
Definition: cs_field.c:1502
void cs_field_log_defs(void)
Print info relative to all field definitions to log file.
Definition: cs_field.c:3701
bool cs_field_is_key_locked(const cs_field_t *f, int key_id)
Query if a given key has been locked for a field.
Definition: cs_field.c:2943
void cs_field_allocate_values(cs_field_t *f)
Allocate arrays for field values.
Definition: cs_field.c:1687
cs_field_t * cs_field_find_or_create(const char *name, int type_flag, int location_id, int dim, bool has_previous)
Return a field matching a given name and attributes, creating it if necessary.
Definition: cs_field.c:1566
int cs_field_set_key_str(cs_field_t *f, int key_id, const char *str)
Assign a character string for a given key to a field.
Definition: cs_field.c:3318
int cs_field_set_key_struct(cs_field_t *f, int key_id, void *s)
Assign a simple structure for a given key to a field.
Definition: cs_field.c:3439
cs_field_error_type_t
Definition: cs_field.h:89
@ CS_FIELD_INVALID_KEY_NAME
Definition: cs_field.h:92
@ CS_FIELD_INVALID_FIELD
Definition: cs_field.h:96
@ CS_FIELD_INVALID_TYPE
Definition: cs_field.h:95
@ CS_FIELD_INVALID_CATEGORY
Definition: cs_field.h:94
@ CS_FIELD_LOCKED
Definition: cs_field.h:97
@ CS_FIELD_OK
Definition: cs_field.h:91
@ CS_FIELD_INVALID_KEY_ID
Definition: cs_field.h:93
void() cs_field_clear_key_struct_t(void *t)
Definition: cs_field.h:188
bool cs_field_is_key_set(const cs_field_t *f, int key_id)
Query if a given key has been set for a field.
Definition: cs_field.c:2912
int cs_field_set_key_int_bits(cs_field_t *f, int key_id, int mask)
Set integer bits matching a mask to 1 for a given key for a field.
Definition: cs_field.c:3139
void cs_field_key_disable_setup_log(int key_id)
Disable logging setup values associated with a given key.
Definition: cs_field.c:2890
void * cs_field_get_key_struct_ptr(cs_field_t *f, int key_id)
Return a pointer to a simple structure for a given key to a field.
Definition: cs_field.c:3564
int cs_field_define_sub_key(const char *name, int parent_id)
Define a sub key.
Definition: cs_field.c:2808
void cs_field_allocate_or_map_all(void)
Allocate arrays for all defined fields based on their location.
Definition: cs_field.c:2289
const void * cs_field_get_key_struct(const cs_field_t *f, int key_id, void *s)
Return a structure for a given key associated with a field.
Definition: cs_field.c:3491
void cs_field_destroy_all(void)
Destroy all defined fields.
Definition: cs_field.c:2228
void cs_field_map_values(cs_field_t *f, cs_real_t *val, cs_real_t *val_pre)
Map existing value arrays to field descriptor.
Definition: cs_field.c:1718
void cs_field_log_info(const cs_field_t *f, int log_keywords)
Print info relative to a given field to log file.
Definition: cs_field.c:3839
void cs_field_log_key_defs(void)
Print info relative to all key definitions to log file.
Definition: cs_field.c:4034
double cs_field_get_key_double(const cs_field_t *f, int key_id)
Return a floating point value for a given key associated with a field.
Definition: cs_field.c:3248
const char * cs_glob_field_comp_name_9[]
const char * cs_glob_field_comp_name_6[]
int cs_field_define_key_struct(const char *name, const void *default_value, cs_field_log_key_struct_t *log_func, cs_field_log_key_struct_t *log_func_default, cs_field_clear_key_struct_t *clear_func, size_t size, int type_flag)
Define a key for a structure value by its name and return an associated id.
Definition: cs_field.c:2755
int cs_field_key_id(const char *name)
Return an id associated with a given key name.
Definition: cs_field.c:2574
int cs_field_define_key_double(const char *name, double default_value, int type_flag)
Define a key for an floating point value by its name and return an associated id.
Definition: cs_field.c:2666
void cs_field_define_keys_base(void)
Define base keys.
Definition: cs_field.c:4343
int cs_field_key_id_try(const char *name)
Return an id associated with a given key name if present.
Definition: cs_field.c:2601
void cs_field_log_fields(int log_keywords)
Print info relative to all defined fields to log file.
Definition: cs_field.c:3973
cs_field_t * cs_field_by_composite_name(const char *name_prefix, const char *name_suffix)
Return a pointer to a field based on a composite name.
Definition: cs_field.c:2394
void cs_field_current_to_previous(cs_field_t *f)
Copy current field values to previous values if applicable.
Definition: cs_field.c:2170
void cs_field_log_all_key_vals(bool log_defaults)
Print info relative to all given field keys to log file.
Definition: cs_field.c:4312
int cs_field_lock_key(cs_field_t *f, int key_id)
Lock a field relative to a given key.
Definition: cs_field.c:2975
void cs_field_allocate_bc_coeffs(cs_field_t *f, bool have_flux_bc, bool have_mom_bc, bool have_conv_bc, bool have_exch_bc)
Allocate boundary condition coefficients arrays.
Definition: cs_field.c:1771
void cs_field_component_id_by_name(const char *name, int *f_id, int *c_id)
Return the id of a defined field and an associated component based on a component name.
Definition: cs_field.c:2485
int cs_field_set_key_double(cs_field_t *f, int key_id, double value)
Assign a floating point value for a given key to a field.
Definition: cs_field.c:3200
int cs_field_id_by_name(const char *name)
Return the id of a defined field based on its name.
Definition: cs_field.c:2464
void() cs_field_log_key_struct_t(const void *t)
Definition: cs_field.h:178
cs_field_t * cs_field_by_name(const char *name)
Return a pointer to a field based on its name.
Definition: cs_field.c:2344
const char * cs_glob_field_comp_name_3[]
void cs_field_allocate_gradient(cs_field_t *f)
Allocate arrays for field gradient.
Definition: cs_field.c:2119
void cs_field_log_key_vals(int key_id, bool log_defaults)
Print info relative to a given field key to log file.
Definition: cs_field.c:4188
@ t
Definition: cs_field_pointer.h:92
Field boundary condition descriptor (for variables)
Definition: cs_field.h:104
cs_real_t * rcodcl2
Definition: cs_field.h:110
cs_real_t * af
Definition: cs_field.h:115
int location_id
Definition: cs_field.h:106
cs_real_t * bc
Definition: cs_field.h:120
cs_real_t * rcodcl3
Definition: cs_field.h:111
cs_real_t * b
Definition: cs_field.h:114
cs_real_t * a
Definition: cs_field.h:113
cs_real_t * ad
Definition: cs_field.h:117
cs_real_t * hint
Definition: cs_field.h:122
cs_real_t * ac
Definition: cs_field.h:119
cs_real_t * rcodcl1
Definition: cs_field.h:109
cs_real_t * bf
Definition: cs_field.h:116
cs_real_t * bd
Definition: cs_field.h:118
int * icodcl
Definition: cs_field.h:108
cs_real_t * _hext
Definition: cs_field.h:123
Field descriptor.
Definition: cs_field.h:131
int location_id
Definition: cs_field.h:140
cs_real_t * grad
Definition: cs_field.h:159
cs_real_t ** vals
Definition: cs_field.h:144
int type
Definition: cs_field.h:136
int n_time_vals
Definition: cs_field.h:142
cs_real_t * val_pre
Definition: cs_field.h:155
const char * name
Definition: cs_field.h:133
bool is_owner
Definition: cs_field.h:166
cs_real_t * val
Definition: cs_field.h:152
int id
Definition: cs_field.h:135
cs_field_bc_coeffs_t * bc_coeffs
Definition: cs_field.h:163
int dim
Definition: cs_field.h:138