8.0
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 
126 
127 /* Field descriptor */
128 /*------------------*/
129 
130 typedef struct {
131 
132  const char *name; /* Canonical name */
133 
134  int id; /* Field id */
135  int type; /* Field type flag */
136 
137  int dim; /* Field dimension */
138 
139  int location_id; /* Id of matching location */
140 
141  int n_time_vals; /* Number of time values */
142 
143  cs_real_t **vals; /* For each active location, pointer
144  to matching values arrays
145  vals[0][:] = val
146  vals[1][:] = val_pre
147  vals[p][:] = p ith previous field
148  p < n_time_vals */
149 
150 
151  cs_real_t *val; /* For each active location, pointer
152  to matching values array */
153 
154  cs_real_t *val_pre; /* For each active location, pointer
155  to matching previous values array
156  (if n_time_vals == 2) */
157 
158  cs_field_bc_coeffs_t *bc_coeffs; /* Boundary condition coefficients,
159  for variable type fields */
160 
161  bool is_owner; /* Ownership flag for values */
162 
163 } cs_field_t;
164 
165 /*----------------------------------------------------------------------------
166  * Function pointer for structure associated to field key
167  *
168  * parameters:
169  * t <-- pointer to structure
170  *----------------------------------------------------------------------------*/
171 
172 typedef void
173 (cs_field_log_key_struct_t) (const void *t);
174 
175 /*----------------------------------------------------------------------------
176  * Function pointer for structure associated to field key
177  *
178  * parameters:
179  * t <-- pointer to structure
180  *----------------------------------------------------------------------------*/
181 
182 typedef void
184 
185 /*============================================================================
186  * Global variables
187  *============================================================================*/
188 
189 /* Names for components */
190 
191 extern const char *cs_glob_field_comp_name_3[];
192 extern const char *cs_glob_field_comp_name_6[];
193 extern const char *cs_glob_field_comp_name_9[];
194 
195 /*=============================================================================
196  * Public function prototypes
197  *============================================================================*/
198 
199 /*----------------------------------------------------------------------------
200  * Return the number of defined fields.
201  *
202  * returns:
203  * number of defined fields.
204  *----------------------------------------------------------------------------*/
205 
206 int
207 cs_field_n_fields(void);
208 
209 /*----------------------------------------------------------------------------
210  * Create a field descriptor.
211  *
212  * parameters:
213  * name <-- field name
214  * type_flag <-- mask of field property and category values
215  * location_id <-- id of associated location
216  * dim <-- field dimension (number of components)
217  * has_previous <-- maintain values at the previous time step ?
218  *
219  * returns:
220  * pointer to new field.
221  *----------------------------------------------------------------------------*/
222 
223 cs_field_t *
224 cs_field_create(const char *name,
225  int type_flag,
226  int location_id,
227  int dim,
228  bool has_previous);
229 
230 /*----------------------------------------------------------------------------*/
249 /*----------------------------------------------------------------------------*/
250 
251 cs_field_t *
252 cs_field_find_or_create(const char *name,
253  int type_flag,
254  int location_id,
255  int dim,
256  bool has_previous);
257 
258 /*----------------------------------------------------------------------------
259  * Change the number of time values managed by a field.
260  *
261  * The minimum will never be below 1, as the current time is always handled.
262  *
263  * parameters:
264  * f <-> pointer to field structure
265  * n_time_vals <-- number of time values to maintain
266  *----------------------------------------------------------------------------*/
267 
268 void
270  int n_time_vals);
271 
272 /*----------------------------------------------------------------------------
273  * Allocate arrays for field values.
274  *
275  * parameters:
276  * f <-- pointer to field structure
277  *----------------------------------------------------------------------------*/
278 
279 void
281 
282 /*----------------------------------------------------------------------------
283  * Map existing value arrays to field descriptor.
284  *
285  * parameters:
286  * f <-> pointer to field structure
287  * val <-- pointer to array of values
288  * val_pre <-- pointer to array of previous values, or NULL
289  *----------------------------------------------------------------------------*/
290 
291 void
293  cs_real_t *val,
294  cs_real_t *val_pre);
295 
296 /*----------------------------------------------------------------------------
297  * Allocate boundary condition coefficient arrays.
298  *
299  * For fields on location CS_MESH_LOCATION_CELLS, boundary conditions
300  * are located on CS_MESH_LOCATION_BOUNDARY_FACES.
301  *
302  * Boundary condition coefficients are not currently supported for other
303  * locations (though support could be added by mapping a boundary->location
304  * indirection array in the cs_mesh_location_t structure).
305  *
306  * For multidimensional fields with coupled components, implicit b and bf
307  * coefficient arrays are arrays of block matrices, not vectors, so the
308  * number of entries for each boundary face is dim*dim instead of dim.
309  *
310  * parameters:
311  * f <-- pointer to field structure
312  * have_flux_bc <-- if true, flux BC coefficients (af and bf) are added
313  * have_mom_bc <-- if true, div BC coefficients (ad and bd) are added
314  * have_conv_bc <-- if true, convection BC coefficients (ac and bc) are added
315  * have_exch_bc <-- if true, exchange boundary coefficients (hint and hext)
316  * are added
317  *----------------------------------------------------------------------------*/
318 
319 void
321  bool have_flux_bc,
322  bool have_mom_bc,
323  bool have_conv_bc,
324  bool have_exch_bc);
325 
326 /*----------------------------------------------------------------------------*/
327 /* Initialize boundary condition coefficients arrays.
328  *
329  * For fields on location CS_MESH_LOCATION_CELLS, boundary conditions
330  * are located on CS_MESH_LOCATION_BOUNDARY_FACES.
331  *
332  * Boundary condition coefficients are not currently supported for other
333  * locations (though support could be added by mapping a boundary->location
334  * indirection array in the cs_mesh_location_t structure).
335  *
336  * For multidimensional fields with coupled components, implicit b and bf
337  * coefficient arrays are arrays of block matrices, not vectors, so the
338  * number of entries for each boundary face is dim*dim instead of dim.
339  *
340  * parameters:
341  * f <-> pointer to field structure
342  *----------------------------------------------------------------------------*/
343 
344 void
346 
347 /*----------------------------------------------------------------------------
348  * Set current field values to the given constant.
349  *
350  * parameters:
351  * f <-> pointer to field structure
352  * c <-- assigned value
353  *----------------------------------------------------------------------------*/
354 
355 void
357  cs_real_t c);
358 
359 /*----------------------------------------------------------------------------
360  * Copy current field values to previous values if applicable.
361  *
362  * For fields with only one time value, or values not allocated yet,
363  * this is a no-op.
364  *
365  * parameters:
366  * f <-> pointer to field structure
367  *----------------------------------------------------------------------------*/
368 
369 void
371 
372 /*----------------------------------------------------------------------------
373  * Destroy all defined fields.
374  *----------------------------------------------------------------------------*/
375 
376 void
378 
379 /*----------------------------------------------------------------------------
380  * Allocate arrays for all defined fields based on their location.
381  *
382  * Location sized must thus be known.
383  *
384  * Fields that do not own their data should all have been mapped at this
385  * stage, and are checked.
386  *----------------------------------------------------------------------------*/
387 
388 void
390 
391 /*----------------------------------------------------------------------------
392  * Return a pointer to a field based on its id.
393  *
394  * This function requires that a field of the given id is defined.
395  *
396  * parameters:
397  * id <-- field id
398  *
399  * returns:
400  * pointer to the field structure
401  *----------------------------------------------------------------------------*/
402 
403 cs_field_t *
404 cs_field_by_id(int id);
405 
406 /*----------------------------------------------------------------------------
407  * Return a pointer to a field based on its name.
408  *
409  * This function requires that a field of the given name is defined.
410  *
411  * parameters:
412  * name <-- field name
413  *
414  * returns:
415  * pointer to the field structure
416  *----------------------------------------------------------------------------*/
417 
418 cs_field_t *
419 cs_field_by_name(const char *name);
420 
421 /*----------------------------------------------------------------------------
422  * Return a pointer to a field based on its name if present.
423  *
424  * If no field of the given name is defined, NULL is returned.
425  *
426  * parameters:
427  * name <-- field name
428  *
429  * returns:
430  * pointer to the field structure, or NULL
431  *----------------------------------------------------------------------------*/
432 
433 cs_field_t *
434 cs_field_by_name_try(const char *name);
435 
436 /*----------------------------------------------------------------------------*/
447 /*----------------------------------------------------------------------------*/
448 
449 cs_field_t *
450 cs_field_by_composite_name(const char *name_prefix,
451  const char *name_suffix);
452 
453 /*----------------------------------------------------------------------------*/
465 /*----------------------------------------------------------------------------*/
466 
467 cs_field_t *
468 cs_field_by_composite_name_try(const char *name_prefix,
469  const char *name_suffix);
470 
471 /*----------------------------------------------------------------------------
472  * Return the id of a defined field based on its name.
473  *
474  * If no field with the given name exists, -1 is returned.
475  *
476  * parameters:
477  * name <-- field name
478  *
479  * returns:
480  * id the field, or -1 if not found
481  *----------------------------------------------------------------------------*/
482 
483 int
484 cs_field_id_by_name(const char *name);
485 
486 /*----------------------------------------------------------------------------
487  * Return the id of a defined field and an associated component
488  * based on a component name.
489  *
490  * If no field with the given name exists, -1 is returned.
491  *
492  * parameters:
493  * name <-- field or field+component name
494  * f_id --> field id, or -1 if no match was found
495  * c_id --> component id, or -1 for all components
496  *----------------------------------------------------------------------------*/
497 
498 void
499 cs_field_component_id_by_name(const char *name,
500  int *f_id,
501  int *c_id);
502 
503 /*----------------------------------------------------------------------------
504  * Return an id associated with a given key name.
505  *
506  * The key must have been defined previously.
507  *
508  * parameters:
509  * name <-- key name
510  *
511  * returns:
512  * id associated with key
513  *----------------------------------------------------------------------------*/
514 
515 int
516 cs_field_key_id(const char *name);
517 
518 /*----------------------------------------------------------------------------
519  * Return an id associated with a given key name if present.
520  *
521  * If the key has not been defined previously, -1 is returned.
522  *
523  * parameters:
524  * name <-- key name
525  *
526  * returns:
527  * id associated with key, or -1
528  *----------------------------------------------------------------------------*/
529 
530 int
531 cs_field_key_id_try(const char *name);
532 
533 /*----------------------------------------------------------------------------
534  * Define a key for an integer value by its name and return an associated id.
535  *
536  * If the key has already been defined, its previous default value is replaced
537  * by the current value, and its id is returned.
538  *
539  * parameters:
540  * name <-- key name
541  * default_value <-- default value associated with key
542  * type flag <-- mask associated with field types with which the
543  * key may be associated, or 0
544  *
545  * returns:
546  * id associated with key
547  *----------------------------------------------------------------------------*/
548 
549 int
550 cs_field_define_key_int(const char *name,
551  int default_value,
552  int type_flag);
553 
554 /*----------------------------------------------------------------------------
555  * Define a key for an floating point value by its name and return an
556  * associated id.
557  *
558  * If the key has already been defined, its previous default value is replaced
559  * by the current value, and its id is returned.
560  *
561  * parameters:
562  * name <-- key name
563  * default_value <-- default value associated with key
564  * type flag <-- mask associated with field types with which the
565  * key may be associated, or 0
566  *
567  * returns:
568  * id associated with key
569  *----------------------------------------------------------------------------*/
570 
571 int
572 cs_field_define_key_double(const char *name,
573  double default_value,
574  int type_flag);
575 
576 /*----------------------------------------------------------------------------
577  * Define a key for an string point value by its name and return an
578  * associated id.
579  *
580  * If the key has already been defined, its previous default value is replaced
581  * by the current value, and its id is returned.
582  *
583  * parameters:
584  * name <-- key name
585  * default_value <-- default value associated with key
586  * type flag <-- mask associated with field types with which the
587  * key may be associated, or 0
588  *
589  * returns:
590  * id associated with key
591  *----------------------------------------------------------------------------*/
592 
593 int
594 cs_field_define_key_str(const char *name,
595  const char *default_value,
596  int type_flag);
597 
598 /*----------------------------------------------------------------------------
599  * Define a key for a structure value by its name and return an
600  * associated id.
601  *
602  * If the key has already been defined, its previous default value is replaced
603  * by the current value, and its id is returned.
604  *
605  * parameters:
606  * name <-- key name
607  * default_value <-- pointer to default value associated with key
608  * log_funct <-- pointer to logging function
609  * log_func_default <-- pointer to default logging function
610  * clear_func <-- pointer to substructures free function
611  * size <-- sizeof structure
612  * type_flag <-- mask associated with field types with which
613  * the key may be associated, or 0
614  *
615  * returns:
616  * id associated with key
617  *----------------------------------------------------------------------------*/
618 
619 int
620 cs_field_define_key_struct(const char *name,
621  const void *default_value,
622  cs_field_log_key_struct_t *log_func,
623  cs_field_log_key_struct_t *log_func_default,
624  cs_field_clear_key_struct_t *clear_func,
625  size_t size,
626  int type_flag);
627 
628 /*----------------------------------------------------------------------------
629  * Define a sub key.
630  *
631  * The sub key is the same type as the parent key.
632  *
633  * For a given field, when querying a sub key's value and that value has not
634  * been set, the query will return the value of the parent key.
635  *
636  * parameters:
637  * name <-- key name
638  * parent_id <-- parent key id
639  *
640  * returns:
641  * id associated with key
642  *----------------------------------------------------------------------------*/
643 
644 int
645 cs_field_define_sub_key(const char *name,
646  int parent_id);
647 
648 /*----------------------------------------------------------------------------
649  * Destroy all defined field keys and associated values.
650  *----------------------------------------------------------------------------*/
651 
652 void
654 
655 /*----------------------------------------------------------------------------
656  * Get the type flag associated with a given key id.
657  *
658  * If the key has not been defined previously, -1 is returned.
659  *
660  * parameters:
661  * key_id <-- id of associated key
662  *
663  * returns:
664  * type flag associated with key, or -1
665  *----------------------------------------------------------------------------*/
666 
667 int
668 cs_field_key_flag(int key_id);
669 
670 /*----------------------------------------------------------------------------
671  * Disable logging setup values associated with a given key.
672  *
673  * This is useful when a key is used not for setup purposes, but to track
674  * values associated with a field, such as convergence or performance data.
675  *
676  * parameters:
677  * key_id <-- id of associated key
678  *----------------------------------------------------------------------------*/
679 
680 void
682 
683 /*----------------------------------------------------------------------------
684  * Query if a given key has been set for a field.
685  *
686  * If the key id is not valid, or the field category is not
687  * compatible, a fatal error is provoked.
688  *
689  * parameters:
690  * f <-- pointer to field structure
691  * key_id <-- id of associated key
692  *
693  * returns:
694  * true if the key has been set for this field, false otherwise
695  *----------------------------------------------------------------------------*/
696 
697 bool
699  int key_id);
700 
701 /*----------------------------------------------------------------------------
702  * Query if a given key has been locked for a field.
703  *
704  * If the key id is not valid, or the field category is not
705  * compatible, a fatal error is provoked.
706  *
707  * parameters:
708  * f <-- pointer to field structure
709  * key_id <-- id of associated key
710  *
711  * returns:
712  * true if the key has been locked for this field, false otherwise
713  *----------------------------------------------------------------------------*/
714 
715 bool
717  int key_id);
718 
719 /*----------------------------------------------------------------------------
720  * Lock a field relative to a given key.
721  *
722  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
723  * If the field category is not compatible with the key (as defined
724  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
725  *
726  * parameters:
727  * f <-- pointer to field structure
728  * key_id <-- id of associated key
729  * value <-- value associated with key
730  *
731  * returns:
732  * 0 in case of success, > 1 in case of error
733  *----------------------------------------------------------------------------*/
734 
735 int
737  int key_id);
738 
739 /*----------------------------------------------------------------------------
740  * Assign a integer value for a given key to a field.
741  *
742  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
743  * If the field category is not compatible with the key (as defined
744  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
745  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
746  * If the key value has been locked, CS_FIELD_LOCKED is returned.
747  *
748  * parameters:
749  * f <-- pointer to field structure
750  * key_id <-- id of associated key
751  * value <-- value associated with key
752  *
753  * returns:
754  * 0 in case of success, > 1 in case of error
755  *----------------------------------------------------------------------------*/
756 
757 int
759  int key_id,
760  int value);
761 
762 /*----------------------------------------------------------------------------
763  * Return a integer value for a given key associated with a field.
764  *
765  * If the key id is not valid, or the value type or field category is not
766  * compatible, a fatal error is provoked.
767  *
768  * parameters:
769  * f <-- pointer to field structure
770  * key_id <-- id of associated key
771  *
772  * returns:
773  * integer value associated with the key id for this field
774  *----------------------------------------------------------------------------*/
775 
776 int
778  int key_id);
779 
780 /*----------------------------------------------------------------------------
781  * Set integer bits matching a mask to 1 for a given key for a field.
782  *
783  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
784  * If the field category is not compatible with the key (as defined
785  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
786  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
787  * If the key value has been locked, CS_FIELD_LOCKED is returned.
788  *
789  * parameters:
790  * f <-- pointer to field structure
791  * key_id <-- id of associated key
792  * mask <-- mask associated with key
793  *
794  * returns:
795  * 0 in case of success, > 1 in case of error
796  *----------------------------------------------------------------------------*/
797 
798 int
800  int key_id,
801  int mask);
802 
803 /*----------------------------------------------------------------------------
804  * Set integer bits matching a mask to 0 for a given key for a field.
805  *
806  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
807  * If the field category is not compatible with the key (as defined
808  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
809  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
810  * If the key value has been locked, CS_FIELD_LOCKED is returned.
811  *
812  * parameters:
813  * f <-- pointer to field structure
814  * key_id <-- id of associated key
815  * mask <-- mask associated with key
816  *
817  * returns:
818  * 0 in case of success, > 1 in case of error
819  *----------------------------------------------------------------------------*/
820 
821 int
823  int key_id,
824  int mask);
825 
826 /*----------------------------------------------------------------------------
827  * Assign a floating point value for a given key to a field.
828  *
829  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
830  * If the field category is not compatible with the key (as defined
831  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
832  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
833  * If the key value has been locked, CS_FIELD_LOCKED is returned.
834  *
835  * parameters:
836  * f <-- pointer to field structure
837  * key_id <-- id of associated key
838  * value <-- value associated with key
839  *
840  * returns:
841  * 0 in case of success, > 1 in case of error
842  *----------------------------------------------------------------------------*/
843 
844 int
846  int key_id,
847  double value);
848 
849 /*----------------------------------------------------------------------------
850  * Return a floating point value for a given key associated with a field.
851  *
852  * If the key id is not valid, or the value type or field category is not
853  * compatible, a fatal error is provoked.
854  *
855  * parameters:
856  * f <-- pointer to field structure
857  * key_id <-- id of associated key
858  *
859  * returns:
860  * floating point value associated with the key id for this field
861  *----------------------------------------------------------------------------*/
862 
863 double
865  int key_id);
866 
867 /*----------------------------------------------------------------------------
868  * Assign a character string value for a given key to a field.
869  *
870  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
871  * If the field category is not compatible with the key (as defined
872  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
873  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
874  * If the key value has been locked, CS_FIELD_LOCKED is returned.
875  *
876  * parameters:
877  * f <-- pointer to field structure
878  * key_id <-- id of associated key
879  * str <-- string associated with key
880  *
881  * returns:
882  * 0 in case of success, > 1 in case of error
883  *----------------------------------------------------------------------------*/
884 
885 int
887  int key_id,
888  const char *str);
889 
890 /*----------------------------------------------------------------------------
891  * Return a string for a given key associated with a field.
892  *
893  * If the key id is not valid, or the value type or field category is not
894  * compatible, a fatal error is provoked.
895  *
896  * parameters:
897  * f <-- pointer to field structure
898  * key_id <-- id of associated key
899  *
900  * returns:
901  * pointer to character string associated with the key id for this field
902  *----------------------------------------------------------------------------*/
903 
904 const char *
906  int key_id);
907 
908 
909 /*----------------------------------------------------------------------------
910  * Assign a simple structure for a given key to a field.
911  *
912  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
913  * If the field category is not compatible with the key (as defined
914  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
915  * If the key value has been locked, CS_FIELD_LOCKED is returned.
916  *
917  * parameters:
918  * f <-- pointer to field structure
919  * key_id <-- id of associated key
920  * s <-- structure associated with key
921  *
922  * returns:
923  * 0 in case of success, > 1 in case of error
924  *----------------------------------------------------------------------------*/
925 
926 int
928  int key_id,
929  void *s);
930 
931 /*----------------------------------------------------------------------------
932  * Return a structure for a given key associated with a field.
933  *
934  * If the key id is not valid, or the value type or field category is not
935  * compatible, a fatal error is provoked.
936  *
937  * parameters:
938  * f <-- pointer to field structure
939  * key_id <-- id of associated key
940  * s <-- structure associated with key
941  *
942  * returns:
943  * pointer to structure associated with the key id for this field
944  * (same as s)
945  *----------------------------------------------------------------------------*/
946 
947 const void *
949  int key_id,
950  void *s);
951 
952 /*----------------------------------------------------------------------------*/
968 /*----------------------------------------------------------------------------*/
969 
970 void *
972  int key_id);
973 
974 /*----------------------------------------------------------------------------*/
987 /*----------------------------------------------------------------------------*/
988 
989 const void *
991  int key_id);
992 
993 /*----------------------------------------------------------------------------
994  * Print info relative to all field definitions to log file.
995  *----------------------------------------------------------------------------*/
996 
997 void
998 cs_field_log_defs(void);
999 
1000 /*----------------------------------------------------------------------------
1001  * Print info relative to a given field to log file.
1002  *
1003  * parameters:
1004  * f <-- pointer to field structure
1005  * log_keywords <-- log level for keywords (0: do not log,
1006  * 1: log non-default values, 2: log all)
1007  *----------------------------------------------------------------------------*/
1008 
1009 void
1010 cs_field_log_info(const cs_field_t *f,
1011  int log_keywords);
1012 
1013 /*----------------------------------------------------------------------------
1014  * Print info relative to all defined fields to log file.
1015  *
1016  * parameters:
1017  * log_keywords <-- log level for keywords (0: do not log,
1018  * 1: log non-default values, 2: log all)
1019  *----------------------------------------------------------------------------*/
1020 
1021 void
1022 cs_field_log_fields(int log_keywords);
1023 
1024 /*----------------------------------------------------------------------------
1025  * Print info relative to all key definitions to log file.
1026  *----------------------------------------------------------------------------*/
1027 
1028 void
1029 cs_field_log_key_defs(void);
1030 
1031 /*----------------------------------------------------------------------------
1032  * Print info relative to a given field key to log file.
1033  *
1034  * parameters:
1035  * int key_id <-- id of associated key
1036  * log_defaults <-- if true, log default field values in addition to
1037  * defined field values
1038  *----------------------------------------------------------------------------*/
1039 
1040 void
1041 cs_field_log_key_vals(int key_id,
1042  bool log_defaults);
1043 
1044 /*----------------------------------------------------------------------------
1045  * Print info relative to all given field keys to log file.
1046  *
1047  * parameters:
1048  * log_defaults <-- if true, log default field values in addition to
1049  * defined field values
1050  *----------------------------------------------------------------------------*/
1051 
1052 void
1053 cs_field_log_all_key_vals(bool log_defaults);
1054 
1055 /*----------------------------------------------------------------------------
1056  * Define base keys.
1057  *
1058  * Keys defined by this function are:
1059  * "label" (string)
1060  * "log" (integer)
1061  * "post_vis" (integer)
1062  * "coupled" (integer, restricted to CS_FIELD_VARIABLE)
1063  * "moment_id" (integer, restricted to
1064  * CS_FIELD_ACCUMULATOR | CS_FIELD_POSTPROCESS);
1065  *
1066  * A recommened practice for different submodules would be to use
1067  * "cs_<module>_key_init() functions to define keys specific to those modules.
1068  *----------------------------------------------------------------------------*/
1069 
1070 void
1072 
1073 /*----------------------------------------------------------------------------
1074  * Return a label associated with a field.
1075  *
1076  * If the "label" key has been set for this field, its associated string
1077  * is returned. Otherwise, the field's name is returned.
1078  *
1079  * parameters:
1080  * f <-- pointer to field structure
1081  *
1082  * returns:
1083  * pointer to character string associated with label for this field
1084  *----------------------------------------------------------------------------*/
1085 
1086 const char *
1087 cs_field_get_label(const cs_field_t *f);
1088 
1089 /*----------------------------------------------------------------------------*/
1090 
1092 
1093 #endif /* __CS_FIELD_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:509
double cs_real_t
Floating-point value.
Definition: cs_defs.h:319
#define END_C_DECLS
Definition: cs_defs.h:510
cs_field_t * cs_field_by_id(int id)
Return a pointer to a field based on its id.
Definition: cs_field.c:2316
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:3638
const char * cs_field_get_label(const cs_field_t *f)
Return a label associated with a field.
Definition: cs_field.c:4365
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:3366
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:3016
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:3166
void cs_field_init_bc_coeffs(cs_field_t *f)
Initialize boundary condition coefficients arrays.
Definition: cs_field.c:1949
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:2418
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:2625
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:1547
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:3064
int cs_field_key_flag(int key_id)
Get the type flag associated with a given key id.
Definition: cs_field.c:2862
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:1651
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:2366
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:2699
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:2145
void cs_field_destroy_all_keys(void)
Destroy all defined field keys and associated values.
Definition: cs_field.c:2830
int cs_field_n_fields(void)
Return the number of defined fields.
Definition: cs_field.c:1527
void cs_field_log_defs(void)
Print info relative to all field definitions to log file.
Definition: cs_field.c:3697
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:2939
void cs_field_allocate_values(cs_field_t *f)
Allocate arrays for field values.
Definition: cs_field.c:1712
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:1591
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:3314
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:3435
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:183
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:2908
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:3135
void cs_field_key_disable_setup_log(int key_id)
Disable logging setup values associated with a given key.
Definition: cs_field.c:2886
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:3560
int cs_field_define_sub_key(const char *name, int parent_id)
Define a sub key.
Definition: cs_field.c:2804
void cs_field_allocate_or_map_all(void)
Allocate arrays for all defined fields based on their location.
Definition: cs_field.c:2285
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:3487
void cs_field_destroy_all(void)
Destroy all defined fields.
Definition: cs_field.c:2230
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:1743
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:3835
void cs_field_log_key_defs(void)
Print info relative to all key definitions to log file.
Definition: cs_field.c:4030
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:3244
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:2751
int cs_field_key_id(const char *name)
Return an id associated with a given key name.
Definition: cs_field.c:2570
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:2662
void cs_field_define_keys_base(void)
Define base keys.
Definition: cs_field.c:4339
int cs_field_key_id_try(const char *name)
Return an id associated with a given key name if present.
Definition: cs_field.c:2597
void cs_field_log_fields(int log_keywords)
Print info relative to all defined fields to log file.
Definition: cs_field.c:3969
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:2390
void cs_field_current_to_previous(cs_field_t *f)
Copy current field values to previous values if applicable.
Definition: cs_field.c:2172
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:4308
int cs_field_lock_key(cs_field_t *f, int key_id)
Lock a field relative to a given key.
Definition: cs_field.c:2971
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:1796
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:2481
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:3196
int cs_field_id_by_name(const char *name)
Return the id of a defined field based on its name.
Definition: cs_field.c:2460
void() cs_field_log_key_struct_t(const void *t)
Definition: cs_field.h:173
cs_field_t * cs_field_by_name(const char *name)
Return a pointer to a field based on its name.
Definition: cs_field.c:2340
const char * cs_glob_field_comp_name_3[]
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:4184
@ 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 * hext
Definition: cs_field.h:123
cs_real_t * bd
Definition: cs_field.h:118
int * icodcl
Definition: cs_field.h:108
Field descriptor.
Definition: cs_field.h:130
int location_id
Definition: cs_field.h:139
cs_real_t ** vals
Definition: cs_field.h:143
int type
Definition: cs_field.h:135
int n_time_vals
Definition: cs_field.h:141
cs_real_t * val_pre
Definition: cs_field.h:154
const char * name
Definition: cs_field.h:132
bool is_owner
Definition: cs_field.h:161
cs_real_t * val
Definition: cs_field.h:151
int id
Definition: cs_field.h:134
cs_field_bc_coeffs_t * bc_coeffs
Definition: cs_field.h:158
int dim
Definition: cs_field.h:137