8.2
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-2024 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  * Create bc_coeffs structure.
206  *
207  * \param[in] bc_coeffs bc coefficients
208  *----------------------------------------------------------------------------*/
209 
210 void
212 
213 /*----------------------------------------------------------------------------
214  * Shallow copy of boundary condition coefficients.
215  *
216  * \param[in] ref source bc coefficients
217  * \param[inout] copy shallow copy of bc coefficients
218  *----------------------------------------------------------------------------*/
219 
220 void
222  cs_field_bc_coeffs_t *copy);
223 
224 /*----------------------------------------------------------------------------
225  * \brief Free copy of boundary condition coefficients.
226  *
227  * \param[in] ref reference bc coefficients
228  * \param[inout] copy shallow copy of bc coefficients
229  *----------------------------------------------------------------------------*/
230 
231 void
233  cs_field_bc_coeffs_t *copy);
234 
235 /*----------------------------------------------------------------------------
236  * Return the number of defined fields.
237  *
238  * returns:
239  * number of defined fields.
240  *----------------------------------------------------------------------------*/
241 
242 int
243 cs_field_n_fields(void);
244 
245 /*----------------------------------------------------------------------------
246  * Create a field descriptor.
247  *
248  * parameters:
249  * name <-- field name
250  * type_flag <-- mask of field property and category values
251  * location_id <-- id of associated location
252  * dim <-- field dimension (number of components)
253  * has_previous <-- maintain values at the previous time step ?
254  *
255  * returns:
256  * pointer to new field.
257  *----------------------------------------------------------------------------*/
258 
259 cs_field_t *
260 cs_field_create(const char *name,
261  int type_flag,
262  int location_id,
263  int dim,
264  bool has_previous);
265 
266 /*----------------------------------------------------------------------------*/
278 /*----------------------------------------------------------------------------*/
279 
280 cs_field_t *
281 cs_field_create_by_composite_name(const char *name_prefix,
282  const char *name_suffix,
283  int type_flag,
284  int location_id,
285  int dim,
286  bool has_previous);
287 
288 /*----------------------------------------------------------------------------*/
307 /*----------------------------------------------------------------------------*/
308 
309 cs_field_t *
310 cs_field_find_or_create(const char *name,
311  int type_flag,
312  int location_id,
313  int dim,
314  bool has_previous);
315 
316 /*----------------------------------------------------------------------------
317  * Change the number of time values managed by a field.
318  *
319  * The minimum will never be below 1, as the current time is always handled.
320  *
321  * parameters:
322  * f <-> pointer to field structure
323  * n_time_vals <-- number of time values to maintain
324  *----------------------------------------------------------------------------*/
325 
326 void
328  int n_time_vals);
329 
330 /*----------------------------------------------------------------------------
331  * Allocate arrays for field values.
332  *
333  * parameters:
334  * f <-- pointer to field structure
335  *----------------------------------------------------------------------------*/
336 
337 void
339 
340 /*----------------------------------------------------------------------------
341  * Map existing value arrays to field descriptor.
342  *
343  * parameters:
344  * f <-> pointer to field structure
345  * val <-- pointer to array of values
346  * val_pre <-- pointer to array of previous values, or NULL
347  *----------------------------------------------------------------------------*/
348 
349 void
351  cs_real_t *val,
352  cs_real_t *val_pre);
353 
354 /*----------------------------------------------------------------------------
355  * Allocate boundary condition coefficient arrays.
356  *
357  * For fields on location CS_MESH_LOCATION_CELLS, boundary conditions
358  * are located on CS_MESH_LOCATION_BOUNDARY_FACES.
359  *
360  * Boundary condition coefficients are not currently supported for other
361  * locations (though support could be added by mapping a boundary->location
362  * indirection array in the cs_mesh_location_t structure).
363  *
364  * For multidimensional fields with coupled components, implicit b and bf
365  * coefficient arrays are arrays of block matrices, not vectors, so the
366  * number of entries for each boundary face is dim*dim instead of dim.
367  *
368  * parameters:
369  * f <-- pointer to field structure
370  * have_flux_bc <-- if true, flux BC coefficients (af and bf) are added
371  * have_mom_bc <-- if true, div BC coefficients (ad and bd) are added
372  * have_conv_bc <-- if true, convection BC coefficients (ac and bc) are added
373  * have_exch_bc <-- if true, exchange boundary coefficients (hint and hext)
374  * are added
375  *----------------------------------------------------------------------------*/
376 
377 void
379  bool have_flux_bc,
380  bool have_mom_bc,
381  bool have_conv_bc,
382  bool have_exch_bc);
383 
384 /*----------------------------------------------------------------------------*/
385 /* Initialize boundary condition coefficients arrays.
386  *
387  * For fields on location CS_MESH_LOCATION_CELLS, boundary conditions
388  * are located on CS_MESH_LOCATION_BOUNDARY_FACES.
389  *
390  * Boundary condition coefficients are not currently supported for other
391  * locations (though support could be added by mapping a boundary->location
392  * indirection array in the cs_mesh_location_t structure).
393  *
394  * For multidimensional fields with coupled components, implicit b and bf
395  * coefficient arrays are arrays of block matrices, not vectors, so the
396  * number of entries for each boundary face is dim*dim instead of dim.
397  *
398  * parameters:
399  * f <-> pointer to field structure
400  *----------------------------------------------------------------------------*/
401 
402 void
404 
405 /*----------------------------------------------------------------------------
406  * Allocate arrays for field gradient.
407  *
408  * parameters:
409  * f <-- pointer to field structure
410  *----------------------------------------------------------------------------*/
411 
412 void
414 
415 /*----------------------------------------------------------------------------
416  * Set current field values to the given constant.
417  *
418  * parameters:
419  * f <-> pointer to field structure
420  * c <-- assigned value
421  *----------------------------------------------------------------------------*/
422 
423 void
425  cs_real_t c);
426 
427 /*----------------------------------------------------------------------------
428  * Copy current field values to previous values if applicable.
429  *
430  * For fields with only one time value, or values not allocated yet,
431  * this is a no-op.
432  *
433  * parameters:
434  * f <-> pointer to field structure
435  *----------------------------------------------------------------------------*/
436 
437 void
439 
440 /*----------------------------------------------------------------------------
441  * Destroy all defined fields.
442  *----------------------------------------------------------------------------*/
443 
444 void
446 
447 /*----------------------------------------------------------------------------
448  * Allocate arrays for all defined fields based on their location.
449  *
450  * Location sized must thus be known.
451  *
452  * Fields that do not own their data should all have been mapped at this
453  * stage, and are checked.
454  *----------------------------------------------------------------------------*/
455 
456 void
458 
459 /*----------------------------------------------------------------------------
460  * Return a pointer to a field based on its id.
461  *
462  * This function requires that a field of the given id is defined.
463  *
464  * parameters:
465  * id <-- field id
466  *
467  * returns:
468  * pointer to the field structure
469  *----------------------------------------------------------------------------*/
470 
471 cs_field_t *
472 cs_field_by_id(int id);
473 
474 /*----------------------------------------------------------------------------
475  * Return a pointer to a field based on its name.
476  *
477  * This function requires that a field of the given name is defined.
478  *
479  * parameters:
480  * name <-- field name
481  *
482  * returns:
483  * pointer to the field structure
484  *----------------------------------------------------------------------------*/
485 
486 cs_field_t *
487 cs_field_by_name(const char *name);
488 
489 /*----------------------------------------------------------------------------
490  * Return a pointer to a field based on its name if present.
491  *
492  * If no field of the given name is defined, NULL is returned.
493  *
494  * parameters:
495  * name <-- field name
496  *
497  * returns:
498  * pointer to the field structure, or NULL
499  *----------------------------------------------------------------------------*/
500 
501 cs_field_t *
502 cs_field_by_name_try(const char *name);
503 
504 /*----------------------------------------------------------------------------*/
515 /*----------------------------------------------------------------------------*/
516 
517 cs_field_t *
518 cs_field_by_composite_name(const char *name_prefix,
519  const char *name_suffix);
520 
521 /*----------------------------------------------------------------------------*/
533 /*----------------------------------------------------------------------------*/
534 
535 cs_field_t *
536 cs_field_by_composite_name_try(const char *name_prefix,
537  const char *name_suffix);
538 
539 /*----------------------------------------------------------------------------
540  * Return the id of a defined field based on its name.
541  *
542  * If no field with the given name exists, -1 is returned.
543  *
544  * parameters:
545  * name <-- field name
546  *
547  * returns:
548  * id the field, or -1 if not found
549  *----------------------------------------------------------------------------*/
550 
551 int
552 cs_field_id_by_name(const char *name);
553 
554 /*----------------------------------------------------------------------------
555  * Return the id of a defined field and an associated component
556  * based on a component name.
557  *
558  * If no field with the given name exists, -1 is returned.
559  *
560  * parameters:
561  * name <-- field or field+component name
562  * f_id --> field id, or -1 if no match was found
563  * c_id --> component id, or -1 for all components
564  *----------------------------------------------------------------------------*/
565 
566 void
567 cs_field_component_id_by_name(const char *name,
568  int *f_id,
569  int *c_id);
570 
571 /*----------------------------------------------------------------------------
572  * Return an id associated with a given key name.
573  *
574  * The key must have been defined previously.
575  *
576  * parameters:
577  * name <-- key name
578  *
579  * returns:
580  * id associated with key
581  *----------------------------------------------------------------------------*/
582 
583 int
584 cs_field_key_id(const char *name);
585 
586 /*----------------------------------------------------------------------------
587  * Return an id associated with a given key name if present.
588  *
589  * If the key has not been defined previously, -1 is returned.
590  *
591  * parameters:
592  * name <-- key name
593  *
594  * returns:
595  * id associated with key, or -1
596  *----------------------------------------------------------------------------*/
597 
598 int
599 cs_field_key_id_try(const char *name);
600 
601 /*----------------------------------------------------------------------------
602  * Define a key for an integer value by its name and return an associated id.
603  *
604  * If the key has already been defined, its previous default value is replaced
605  * by the current value, and its id is returned.
606  *
607  * parameters:
608  * name <-- key name
609  * default_value <-- default value associated with key
610  * type flag <-- mask associated with field types with which the
611  * key may be associated, or 0
612  *
613  * returns:
614  * id associated with key
615  *----------------------------------------------------------------------------*/
616 
617 int
618 cs_field_define_key_int(const char *name,
619  int default_value,
620  int type_flag);
621 
622 /*----------------------------------------------------------------------------
623  * Define a key for an floating point value by its name and return an
624  * associated id.
625  *
626  * If the key has already been defined, its previous default value is replaced
627  * by the current value, and its id is returned.
628  *
629  * parameters:
630  * name <-- key name
631  * default_value <-- default value associated with key
632  * type flag <-- mask associated with field types with which the
633  * key may be associated, or 0
634  *
635  * returns:
636  * id associated with key
637  *----------------------------------------------------------------------------*/
638 
639 int
640 cs_field_define_key_double(const char *name,
641  double default_value,
642  int type_flag);
643 
644 /*----------------------------------------------------------------------------
645  * Define a key for an string point value by its name and return an
646  * associated id.
647  *
648  * If the key has already been defined, its previous default value is replaced
649  * by the current value, and its id is returned.
650  *
651  * parameters:
652  * name <-- key name
653  * default_value <-- default value associated with key
654  * type flag <-- mask associated with field types with which the
655  * key may be associated, or 0
656  *
657  * returns:
658  * id associated with key
659  *----------------------------------------------------------------------------*/
660 
661 int
662 cs_field_define_key_str(const char *name,
663  const char *default_value,
664  int type_flag);
665 
666 /*----------------------------------------------------------------------------
667  * Define a key for a structure value by its name and return an
668  * associated id.
669  *
670  * If the key has already been defined, its previous default value is replaced
671  * by the current value, and its id is returned.
672  *
673  * parameters:
674  * name <-- key name
675  * default_value <-- pointer to default value associated with key
676  * log_funct <-- pointer to logging function
677  * log_func_default <-- pointer to default logging function
678  * clear_func <-- pointer to substructures free function
679  * size <-- sizeof structure
680  * type_flag <-- mask associated with field types with which
681  * the key may be associated, or 0
682  *
683  * returns:
684  * id associated with key
685  *----------------------------------------------------------------------------*/
686 
687 int
688 cs_field_define_key_struct(const char *name,
689  const void *default_value,
690  cs_field_log_key_struct_t *log_func,
691  cs_field_log_key_struct_t *log_func_default,
692  cs_field_clear_key_struct_t *clear_func,
693  size_t size,
694  int type_flag);
695 
696 /*----------------------------------------------------------------------------
697  * Define a sub key.
698  *
699  * The sub key is the same type as the parent key.
700  *
701  * For a given field, when querying a sub key's value and that value has not
702  * been set, the query will return the value of the parent key.
703  *
704  * parameters:
705  * name <-- key name
706  * parent_id <-- parent key id
707  *
708  * returns:
709  * id associated with key
710  *----------------------------------------------------------------------------*/
711 
712 int
713 cs_field_define_sub_key(const char *name,
714  int parent_id);
715 
716 /*----------------------------------------------------------------------------
717  * Destroy all defined field keys and associated values.
718  *----------------------------------------------------------------------------*/
719 
720 void
722 
723 /*----------------------------------------------------------------------------
724  * Get the type flag associated with a given key id.
725  *
726  * If the key has not been defined previously, -1 is returned.
727  *
728  * parameters:
729  * key_id <-- id of associated key
730  *
731  * returns:
732  * type flag associated with key, or -1
733  *----------------------------------------------------------------------------*/
734 
735 int
736 cs_field_key_flag(int key_id);
737 
738 /*----------------------------------------------------------------------------
739  * Disable logging setup values associated with a given key.
740  *
741  * This is useful when a key is used not for setup purposes, but to track
742  * values associated with a field, such as convergence or performance data.
743  *
744  * parameters:
745  * key_id <-- id of associated key
746  *----------------------------------------------------------------------------*/
747 
748 void
750 
751 /*----------------------------------------------------------------------------
752  * Query if a given key has been set for a field.
753  *
754  * If the key id is not valid, or the field category is not
755  * compatible, a fatal error is provoked.
756  *
757  * parameters:
758  * f <-- pointer to field structure
759  * key_id <-- id of associated key
760  *
761  * returns:
762  * true if the key has been set for this field, false otherwise
763  *----------------------------------------------------------------------------*/
764 
765 bool
767  int key_id);
768 
769 /*----------------------------------------------------------------------------
770  * Query if a given key has been locked for a field.
771  *
772  * If the key id is not valid, or the field category is not
773  * compatible, a fatal error is provoked.
774  *
775  * parameters:
776  * f <-- pointer to field structure
777  * key_id <-- id of associated key
778  *
779  * returns:
780  * true if the key has been locked for this field, false otherwise
781  *----------------------------------------------------------------------------*/
782 
783 bool
785  int key_id);
786 
787 /*----------------------------------------------------------------------------
788  * Lock a field relative to a given key.
789  *
790  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
791  * If the field category is not compatible with the key (as defined
792  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
793  *
794  * parameters:
795  * f <-- pointer to field structure
796  * key_id <-- id of associated key
797  * value <-- value associated with key
798  *
799  * returns:
800  * 0 in case of success, > 1 in case of error
801  *----------------------------------------------------------------------------*/
802 
803 int
805  int key_id);
806 
807 /*----------------------------------------------------------------------------
808  * Assign a integer value for a given key to a field.
809  *
810  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
811  * If the field category is not compatible with the key (as defined
812  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
813  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
814  * If the key value has been locked, CS_FIELD_LOCKED is returned.
815  *
816  * parameters:
817  * f <-- pointer to field structure
818  * key_id <-- id of associated key
819  * value <-- value associated with key
820  *
821  * returns:
822  * 0 in case of success, > 1 in case of error
823  *----------------------------------------------------------------------------*/
824 
825 int
827  int key_id,
828  int value);
829 
830 /*----------------------------------------------------------------------------
831  * Return a integer value for a given key associated with a field.
832  *
833  * If the key id is not valid, or the value type or field category is not
834  * compatible, a fatal error is provoked.
835  *
836  * parameters:
837  * f <-- pointer to field structure
838  * key_id <-- id of associated key
839  *
840  * returns:
841  * integer value associated with the key id for this field
842  *----------------------------------------------------------------------------*/
843 
844 int
846  int key_id);
847 
848 /*----------------------------------------------------------------------------
849  * Set integer bits matching a mask to 1 for a given key for a field.
850  *
851  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
852  * If the field category is not compatible with the key (as defined
853  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
854  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
855  * If the key value has been locked, CS_FIELD_LOCKED is returned.
856  *
857  * parameters:
858  * f <-- pointer to field structure
859  * key_id <-- id of associated key
860  * mask <-- mask associated with key
861  *
862  * returns:
863  * 0 in case of success, > 1 in case of error
864  *----------------------------------------------------------------------------*/
865 
866 int
868  int key_id,
869  int mask);
870 
871 /*----------------------------------------------------------------------------
872  * Set integer bits matching a mask to 0 for a given key for a field.
873  *
874  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
875  * If the field category is not compatible with the key (as defined
876  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
877  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
878  * If the key value has been locked, CS_FIELD_LOCKED is returned.
879  *
880  * parameters:
881  * f <-- pointer to field structure
882  * key_id <-- id of associated key
883  * mask <-- mask associated with key
884  *
885  * returns:
886  * 0 in case of success, > 1 in case of error
887  *----------------------------------------------------------------------------*/
888 
889 int
891  int key_id,
892  int mask);
893 
894 /*----------------------------------------------------------------------------
895  * Assign a floating point value for a given key to a field.
896  *
897  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
898  * If the field category is not compatible with the key (as defined
899  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
900  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
901  * If the key value has been locked, CS_FIELD_LOCKED is returned.
902  *
903  * parameters:
904  * f <-- pointer to field structure
905  * key_id <-- id of associated key
906  * value <-- value associated with key
907  *
908  * returns:
909  * 0 in case of success, > 1 in case of error
910  *----------------------------------------------------------------------------*/
911 
912 int
914  int key_id,
915  double value);
916 
917 /*----------------------------------------------------------------------------
918  * Return a floating point value for a given key associated with a field.
919  *
920  * If the key id is not valid, or the value type or field category is not
921  * compatible, a fatal error is provoked.
922  *
923  * parameters:
924  * f <-- pointer to field structure
925  * key_id <-- id of associated key
926  *
927  * returns:
928  * floating point value associated with the key id for this field
929  *----------------------------------------------------------------------------*/
930 
931 double
933  int key_id);
934 
935 /*----------------------------------------------------------------------------
936  * Assign a character string value for a given key to a field.
937  *
938  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
939  * If the field category is not compatible with the key (as defined
940  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
941  * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
942  * If the key value has been locked, CS_FIELD_LOCKED is returned.
943  *
944  * parameters:
945  * f <-- pointer to field structure
946  * key_id <-- id of associated key
947  * str <-- string associated with key
948  *
949  * returns:
950  * 0 in case of success, > 1 in case of error
951  *----------------------------------------------------------------------------*/
952 
953 int
955  int key_id,
956  const char *str);
957 
958 /*----------------------------------------------------------------------------
959  * Return a string for a given key associated with a field.
960  *
961  * If the key id is not valid, or the value type or field category is not
962  * compatible, a fatal error is provoked.
963  *
964  * parameters:
965  * f <-- pointer to field structure
966  * key_id <-- id of associated key
967  *
968  * returns:
969  * pointer to character string associated with the key id for this field
970  *----------------------------------------------------------------------------*/
971 
972 const char *
974  int key_id);
975 
976 
977 /*----------------------------------------------------------------------------
978  * Assign a simple structure for a given key to a field.
979  *
980  * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
981  * If the field category is not compatible with the key (as defined
982  * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
983  * If the key value has been locked, CS_FIELD_LOCKED is returned.
984  *
985  * parameters:
986  * f <-- pointer to field structure
987  * key_id <-- id of associated key
988  * s <-- structure associated with key
989  *
990  * returns:
991  * 0 in case of success, > 1 in case of error
992  *----------------------------------------------------------------------------*/
993 
994 int
996  int key_id,
997  void *s);
998 
999 /*----------------------------------------------------------------------------
1000  * Return a structure for a given key associated with a field.
1001  *
1002  * If the key id is not valid, or the value type or field category is not
1003  * compatible, a fatal error is provoked.
1004  *
1005  * parameters:
1006  * f <-- pointer to field structure
1007  * key_id <-- id of associated key
1008  * s <-- structure associated with key
1009  *
1010  * returns:
1011  * pointer to structure associated with the key id for this field
1012  * (same as s)
1013  *----------------------------------------------------------------------------*/
1014 
1015 const void *
1017  int key_id,
1018  void *s);
1019 
1020 /*----------------------------------------------------------------------------*/
1036 /*----------------------------------------------------------------------------*/
1037 
1038 void *
1040  int key_id);
1041 
1042 /*----------------------------------------------------------------------------*/
1055 /*----------------------------------------------------------------------------*/
1056 
1057 const void *
1059  int key_id);
1060 
1061 /*----------------------------------------------------------------------------
1062  * Print info relative to all field definitions to log file.
1063  *----------------------------------------------------------------------------*/
1064 
1065 void
1066 cs_field_log_defs(void);
1067 
1068 /*----------------------------------------------------------------------------
1069  * Print info relative to a given field to log file.
1070  *
1071  * parameters:
1072  * f <-- pointer to field structure
1073  * log_keywords <-- log level for keywords (0: do not log,
1074  * 1: log non-default values, 2: log all)
1075  *----------------------------------------------------------------------------*/
1076 
1077 void
1078 cs_field_log_info(const cs_field_t *f,
1079  int log_keywords);
1080 
1081 /*----------------------------------------------------------------------------
1082  * Print info relative to all defined fields to log file.
1083  *
1084  * parameters:
1085  * log_keywords <-- log level for keywords (0: do not log,
1086  * 1: log non-default values, 2: log all)
1087  *----------------------------------------------------------------------------*/
1088 
1089 void
1090 cs_field_log_fields(int log_keywords);
1091 
1092 /*----------------------------------------------------------------------------
1093  * Print info relative to all key definitions to log file.
1094  *----------------------------------------------------------------------------*/
1095 
1096 void
1097 cs_field_log_key_defs(void);
1098 
1099 /*----------------------------------------------------------------------------
1100  * Print info relative to a given field key to log file.
1101  *
1102  * parameters:
1103  * int key_id <-- id of associated key
1104  * log_defaults <-- if true, log default field values in addition to
1105  * defined field values
1106  *----------------------------------------------------------------------------*/
1107 
1108 void
1109 cs_field_log_key_vals(int key_id,
1110  bool log_defaults);
1111 
1112 /*----------------------------------------------------------------------------
1113  * Print info relative to all given field keys to log file.
1114  *
1115  * parameters:
1116  * log_defaults <-- if true, log default field values in addition to
1117  * defined field values
1118  *----------------------------------------------------------------------------*/
1119 
1120 void
1121 cs_field_log_all_key_vals(bool log_defaults);
1122 
1123 /*----------------------------------------------------------------------------
1124  * Define base keys.
1125  *
1126  * Keys defined by this function are:
1127  * "label" (string)
1128  * "log" (integer)
1129  * "post_vis" (integer)
1130  * "coupled" (integer, restricted to CS_FIELD_VARIABLE)
1131  * "moment_id" (integer, restricted to
1132  * CS_FIELD_ACCUMULATOR | CS_FIELD_POSTPROCESS);
1133  *
1134  * A recommened practice for different submodules would be to use
1135  * "cs_<module>_key_init() functions to define keys specific to those modules.
1136  *----------------------------------------------------------------------------*/
1137 
1138 void
1140 
1141 /*----------------------------------------------------------------------------
1142  * Return a label associated with a field.
1143  *
1144  * If the "label" key has been set for this field, its associated string
1145  * is returned. Otherwise, the field's name is returned.
1146  *
1147  * parameters:
1148  * f <-- pointer to field structure
1149  *
1150  * returns:
1151  * pointer to character string associated with label for this field
1152  *----------------------------------------------------------------------------*/
1153 
1154 const char *
1155 cs_field_get_label(const cs_field_t *f);
1156 
1157 /*----------------------------------------------------------------------------*/
1158 
1160 
1161 #endif /* __CS_FIELD_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:528
double cs_real_t
Floating-point value.
Definition: cs_defs.h:332
#define END_C_DECLS
Definition: cs_defs.h:529
cs_field_t * cs_field_by_id(int id)
Return a pointer to a field based on its id.
Definition: cs_field.c:2465
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:3787
const char * cs_field_get_label(const cs_field_t *f)
Return a label associated with a field.
Definition: cs_field.c:4514
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:3515
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:3165
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:3315
void cs_field_bc_coeffs_init(cs_field_bc_coeffs_t *bc_coeffs)
Definition: cs_field.c:1501
void cs_field_init_bc_coeffs(cs_field_t *f)
Initialize boundary condition coefficients arrays.
Definition: cs_field.c:2069
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:2567
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:2774
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:1613
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:3213
cs_field_t * cs_field_create_by_composite_name(const char *name_prefix, const char *name_suffix, int type_flag, int location_id, int dim, bool has_previous)
Create a field descriptor.
Definition: cs_field.c:1650
int cs_field_key_flag(int key_id)
Get the type flag associated with a given key id.
Definition: cs_field.c:3011
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:1767
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:2515
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:2848
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:2288
void cs_field_destroy_all_keys(void)
Destroy all defined field keys and associated values.
Definition: cs_field.c:2979
int cs_field_n_fields(void)
Return the number of defined fields.
Definition: cs_field.c:1593
void cs_field_log_defs(void)
Print info relative to all field definitions to log file.
Definition: cs_field.c:3846
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:3088
void cs_field_allocate_values(cs_field_t *f)
Allocate arrays for field values.
Definition: cs_field.c:1828
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:1707
void cs_field_bc_coeffs_shallow_copy(const cs_field_bc_coeffs_t *ref, cs_field_bc_coeffs_t *copy)
Shallow copy of boundary condition coefficients.
Definition: cs_field.c:1533
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:3463
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:3584
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:3057
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:3284
void cs_field_key_disable_setup_log(int key_id)
Disable logging setup values associated with a given key.
Definition: cs_field.c:3035
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:3709
int cs_field_define_sub_key(const char *name, int parent_id)
Define a sub key.
Definition: cs_field.c:2953
void cs_field_allocate_or_map_all(void)
Allocate arrays for all defined fields based on their location.
Definition: cs_field.c:2434
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:3636
void cs_field_bc_coeffs_free_copy(const cs_field_bc_coeffs_t *ref, cs_field_bc_coeffs_t *copy)
Free copy of boundary condition coefficients.
Definition: cs_field.c:1556
void cs_field_destroy_all(void)
Destroy all defined fields.
Definition: cs_field.c:2373
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:1859
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:3984
void cs_field_log_key_defs(void)
Print info relative to all key definitions to log file.
Definition: cs_field.c:4179
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:3393
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:2900
int cs_field_key_id(const char *name)
Return an id associated with a given key name.
Definition: cs_field.c:2719
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:2811
void cs_field_define_keys_base(void)
Define base keys.
Definition: cs_field.c:4488
int cs_field_key_id_try(const char *name)
Return an id associated with a given key name if present.
Definition: cs_field.c:2746
void cs_field_log_fields(int log_keywords)
Print info relative to all defined fields to log file.
Definition: cs_field.c:4118
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:2539
void cs_field_current_to_previous(cs_field_t *f)
Copy current field values to previous values if applicable.
Definition: cs_field.c:2315
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:4457
int cs_field_lock_key(cs_field_t *f, int key_id)
Lock a field relative to a given key.
Definition: cs_field.c:3120
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:1912
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:2630
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:3345
int cs_field_id_by_name(const char *name)
Return the id of a defined field based on its name.
Definition: cs_field.c:2609
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:2489
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:2264
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:4333
@ 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