8.3
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
89typedef enum {
90
98
100
102/*------------------------------------------------------*/
103
104typedef 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
131typedef 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
177typedef 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
187typedef void
189
190/*============================================================================
191 * Global variables
192 *============================================================================*/
193
194/* Names for components */
195
196extern const char *cs_glob_field_comp_name_3[];
197extern const char *cs_glob_field_comp_name_6[];
198extern 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
210void
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
220void
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
231void
234
235/*----------------------------------------------------------------------------
236 * Return the number of defined fields.
237 *
238 * returns:
239 * number of defined fields.
240 *----------------------------------------------------------------------------*/
241
242int
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
260cs_field_create(const char *name,
261 int type_flag,
262 int location_id,
263 int dim,
264 bool has_previous);
265
266/*----------------------------------------------------------------------------*/
278/*----------------------------------------------------------------------------*/
279
281cs_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
310cs_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
326void
328 int n_time_vals);
329
330/*----------------------------------------------------------------------------
331 * Allocate arrays for field values.
332 *
333 * parameters:
334 * f <-- pointer to field structure
335 *----------------------------------------------------------------------------*/
336
337void
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 nullptr
347 *----------------------------------------------------------------------------*/
348
349void
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
377void
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
402void
404
405/*----------------------------------------------------------------------------
406 * Allocate arrays for field gradient.
407 *
408 * parameters:
409 * f <-- pointer to field structure
410 *----------------------------------------------------------------------------*/
411
412void
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
423void
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
437void
439
440/*----------------------------------------------------------------------------
441 * Destroy all defined fields.
442 *----------------------------------------------------------------------------*/
443
444void
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
456void
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
472cs_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
487cs_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, nullptr is returned.
493 *
494 * parameters:
495 * name <-- field name
496 *
497 * returns:
498 * pointer to the field structure, or nullptr
499 *----------------------------------------------------------------------------*/
500
502cs_field_by_name_try(const char *name);
503
504/*----------------------------------------------------------------------------*/
515/*----------------------------------------------------------------------------*/
516
518cs_field_by_composite_name(const char *name_prefix,
519 const char *name_suffix);
520
521/*----------------------------------------------------------------------------*/
536/*----------------------------------------------------------------------------*/
537
539cs_field_by_composite_name_try(const char *name_prefix,
540 const char *name_suffix);
541
542/*----------------------------------------------------------------------------*/
561/*----------------------------------------------------------------------------*/
562
564cs_field_by_double_composite_name_try(const char *name_part_1,
565 const char *name_part_2,
566 const char *name_part_3);
567
568/*----------------------------------------------------------------------------
569 * Return the id of a defined field based on its name.
570 *
571 * If no field with the given name exists, -1 is returned.
572 *
573 * parameters:
574 * name <-- field name
575 *
576 * returns:
577 * id the field, or -1 if not found
578 *----------------------------------------------------------------------------*/
579
580int
581cs_field_id_by_name(const char *name);
582
583/*----------------------------------------------------------------------------
584 * Return the id of a defined field and an associated component
585 * based on a component name.
586 *
587 * If no field with the given name exists, -1 is returned.
588 *
589 * parameters:
590 * name <-- field or field+component name
591 * f_id --> field id, or -1 if no match was found
592 * c_id --> component id, or -1 for all components
593 *----------------------------------------------------------------------------*/
594
595void
596cs_field_component_id_by_name(const char *name,
597 int *f_id,
598 int *c_id);
599
600/*----------------------------------------------------------------------------
601 * Return an id associated with a given key name.
602 *
603 * The key must have been defined previously.
604 *
605 * parameters:
606 * name <-- key name
607 *
608 * returns:
609 * id associated with key
610 *----------------------------------------------------------------------------*/
611
612int
613cs_field_key_id(const char *name);
614
615/*----------------------------------------------------------------------------
616 * Return an id associated with a given key name if present.
617 *
618 * If the key has not been defined previously, -1 is returned.
619 *
620 * parameters:
621 * name <-- key name
622 *
623 * returns:
624 * id associated with key, or -1
625 *----------------------------------------------------------------------------*/
626
627int
628cs_field_key_id_try(const char *name);
629
630/*----------------------------------------------------------------------------
631 * Define a key for an integer value by its name and return an associated id.
632 *
633 * If the key has already been defined, its previous default value is replaced
634 * by the current value, and its id is returned.
635 *
636 * parameters:
637 * name <-- key name
638 * default_value <-- default value associated with key
639 * type flag <-- mask associated with field types with which the
640 * key may be associated, or 0
641 *
642 * returns:
643 * id associated with key
644 *----------------------------------------------------------------------------*/
645
646int
647cs_field_define_key_int(const char *name,
648 int default_value,
649 int type_flag);
650
651/*----------------------------------------------------------------------------
652 * Define a key for an floating point value by its name and return an
653 * associated id.
654 *
655 * If the key has already been defined, its previous default value is replaced
656 * by the current value, and its id is returned.
657 *
658 * parameters:
659 * name <-- key name
660 * default_value <-- default value associated with key
661 * type flag <-- mask associated with field types with which the
662 * key may be associated, or 0
663 *
664 * returns:
665 * id associated with key
666 *----------------------------------------------------------------------------*/
667
668int
669cs_field_define_key_double(const char *name,
670 double default_value,
671 int type_flag);
672
673/*----------------------------------------------------------------------------
674 * Define a key for an string point value by its name and return an
675 * associated id.
676 *
677 * If the key has already been defined, its previous default value is replaced
678 * by the current value, and its id is returned.
679 *
680 * parameters:
681 * name <-- key name
682 * default_value <-- default value associated with key
683 * type flag <-- mask associated with field types with which the
684 * key may be associated, or 0
685 *
686 * returns:
687 * id associated with key
688 *----------------------------------------------------------------------------*/
689
690int
691cs_field_define_key_str(const char *name,
692 const char *default_value,
693 int type_flag);
694
695/*----------------------------------------------------------------------------
696 * Define a key for a structure value by its name and return an
697 * associated id.
698 *
699 * If the key has already been defined, its previous default value is replaced
700 * by the current value, and its id is returned.
701 *
702 * parameters:
703 * name <-- key name
704 * default_value <-- pointer to default value associated with key
705 * log_funct <-- pointer to logging function
706 * log_func_default <-- pointer to default logging function
707 * clear_func <-- pointer to substructures free function
708 * size <-- sizeof structure
709 * type_flag <-- mask associated with field types with which
710 * the key may be associated, or 0
711 *
712 * returns:
713 * id associated with key
714 *----------------------------------------------------------------------------*/
715
716int
717cs_field_define_key_struct(const char *name,
718 const void *default_value,
720 cs_field_log_key_struct_t *log_func_default,
721 cs_field_clear_key_struct_t *clear_func,
722 size_t size,
723 int type_flag);
724
725/*----------------------------------------------------------------------------
726 * Define a sub key.
727 *
728 * The sub key is the same type as the parent key.
729 *
730 * For a given field, when querying a sub key's value and that value has not
731 * been set, the query will return the value of the parent key.
732 *
733 * parameters:
734 * name <-- key name
735 * parent_id <-- parent key id
736 *
737 * returns:
738 * id associated with key
739 *----------------------------------------------------------------------------*/
740
741int
742cs_field_define_sub_key(const char *name,
743 int parent_id);
744
745/*----------------------------------------------------------------------------
746 * Destroy all defined field keys and associated values.
747 *----------------------------------------------------------------------------*/
748
749void
751
752/*----------------------------------------------------------------------------
753 * Get the type flag associated with a given key id.
754 *
755 * If the key has not been defined previously, -1 is returned.
756 *
757 * parameters:
758 * key_id <-- id of associated key
759 *
760 * returns:
761 * type flag associated with key, or -1
762 *----------------------------------------------------------------------------*/
763
764int
765cs_field_key_flag(int key_id);
766
767/*----------------------------------------------------------------------------
768 * Disable logging setup values associated with a given key.
769 *
770 * This is useful when a key is used not for setup purposes, but to track
771 * values associated with a field, such as convergence or performance data.
772 *
773 * parameters:
774 * key_id <-- id of associated key
775 *----------------------------------------------------------------------------*/
776
777void
779
780/*----------------------------------------------------------------------------
781 * Query if a given key has been set for a field.
782 *
783 * If the key id is not valid, or the field category is not
784 * compatible, a fatal error is provoked.
785 *
786 * parameters:
787 * f <-- pointer to field structure
788 * key_id <-- id of associated key
789 *
790 * returns:
791 * true if the key has been set for this field, false otherwise
792 *----------------------------------------------------------------------------*/
793
794bool
796 int key_id);
797
798/*----------------------------------------------------------------------------
799 * Query if a given key has been locked for a field.
800 *
801 * If the key id is not valid, or the field category is not
802 * compatible, a fatal error is provoked.
803 *
804 * parameters:
805 * f <-- pointer to field structure
806 * key_id <-- id of associated key
807 *
808 * returns:
809 * true if the key has been locked for this field, false otherwise
810 *----------------------------------------------------------------------------*/
811
812bool
814 int key_id);
815
816/*----------------------------------------------------------------------------
817 * Lock a field relative to a given key.
818 *
819 * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
820 * If the field category is not compatible with the key (as defined
821 * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
822 *
823 * parameters:
824 * f <-- pointer to field structure
825 * key_id <-- id of associated key
826 * value <-- value associated with key
827 *
828 * returns:
829 * 0 in case of success, > 1 in case of error
830 *----------------------------------------------------------------------------*/
831
832int
834 int key_id);
835
836/*----------------------------------------------------------------------------
837 * Assign a integer value for a given key to a field.
838 *
839 * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
840 * If the field category is not compatible with the key (as defined
841 * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
842 * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
843 * If the key value has been locked, CS_FIELD_LOCKED is returned.
844 *
845 * parameters:
846 * f <-- pointer to field structure
847 * key_id <-- id of associated key
848 * value <-- value associated with key
849 *
850 * returns:
851 * 0 in case of success, > 1 in case of error
852 *----------------------------------------------------------------------------*/
853
854int
856 int key_id,
857 int value);
858
859/*----------------------------------------------------------------------------
860 * Return a integer value for a given key associated with a field.
861 *
862 * If the key id is not valid, or the value type or field category is not
863 * compatible, a fatal error is provoked.
864 *
865 * parameters:
866 * f <-- pointer to field structure
867 * key_id <-- id of associated key
868 *
869 * returns:
870 * integer value associated with the key id for this field
871 *----------------------------------------------------------------------------*/
872
873int
875 int key_id);
876
877/*----------------------------------------------------------------------------
878 * Set integer bits matching a mask to 1 for a given key for a field.
879 *
880 * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
881 * If the field category is not compatible with the key (as defined
882 * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
883 * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
884 * If the key value has been locked, CS_FIELD_LOCKED is returned.
885 *
886 * parameters:
887 * f <-- pointer to field structure
888 * key_id <-- id of associated key
889 * mask <-- mask associated with key
890 *
891 * returns:
892 * 0 in case of success, > 1 in case of error
893 *----------------------------------------------------------------------------*/
894
895int
897 int key_id,
898 int mask);
899
900/*----------------------------------------------------------------------------
901 * Set integer bits matching a mask to 0 for a given key for a field.
902 *
903 * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
904 * If the field category is not compatible with the key (as defined
905 * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
906 * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
907 * If the key value has been locked, CS_FIELD_LOCKED is returned.
908 *
909 * parameters:
910 * f <-- pointer to field structure
911 * key_id <-- id of associated key
912 * mask <-- mask associated with key
913 *
914 * returns:
915 * 0 in case of success, > 1 in case of error
916 *----------------------------------------------------------------------------*/
917
918int
920 int key_id,
921 int mask);
922
923/*----------------------------------------------------------------------------
924 * Assign a floating point value for a given key to a field.
925 *
926 * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
927 * If the field category is not compatible with the key (as defined
928 * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
929 * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
930 * If the key value has been locked, CS_FIELD_LOCKED is returned.
931 *
932 * parameters:
933 * f <-- pointer to field structure
934 * key_id <-- id of associated key
935 * value <-- value associated with key
936 *
937 * returns:
938 * 0 in case of success, > 1 in case of error
939 *----------------------------------------------------------------------------*/
940
941int
943 int key_id,
944 double value);
945
946/*----------------------------------------------------------------------------
947 * Return a floating point value for a given key associated with a field.
948 *
949 * If the key id is not valid, or the value type or field category is not
950 * compatible, a fatal error is provoked.
951 *
952 * parameters:
953 * f <-- pointer to field structure
954 * key_id <-- id of associated key
955 *
956 * returns:
957 * floating point value associated with the key id for this field
958 *----------------------------------------------------------------------------*/
959
960double
962 int key_id);
963
964/*----------------------------------------------------------------------------
965 * Assign a character string value for a given key to a field.
966 *
967 * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
968 * If the field category is not compatible with the key (as defined
969 * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
970 * If the data type does not match, CS_FIELD_INVALID_TYPE is returned.
971 * If the key value has been locked, CS_FIELD_LOCKED is returned.
972 *
973 * parameters:
974 * f <-- pointer to field structure
975 * key_id <-- id of associated key
976 * str <-- string associated with key
977 *
978 * returns:
979 * 0 in case of success, > 1 in case of error
980 *----------------------------------------------------------------------------*/
981
982int
984 int key_id,
985 const char *str);
986
987/*----------------------------------------------------------------------------
988 * Return a string for a given key associated with a field.
989 *
990 * If the key id is not valid, or the value type or field category is not
991 * compatible, a fatal error is provoked.
992 *
993 * parameters:
994 * f <-- pointer to field structure
995 * key_id <-- id of associated key
996 *
997 * returns:
998 * pointer to character string associated with the key id for this field
999 *----------------------------------------------------------------------------*/
1000
1001const char *
1003 int key_id);
1004
1005
1006/*----------------------------------------------------------------------------
1007 * Assign a simple structure for a given key to a field.
1008 *
1009 * If the key id is not valid, CS_FIELD_INVALID_KEY_ID is returned.
1010 * If the field category is not compatible with the key (as defined
1011 * by its type flag), CS_FIELD_INVALID_CATEGORY is returned.
1012 * If the key value has been locked, CS_FIELD_LOCKED is returned.
1013 *
1014 * parameters:
1015 * f <-- pointer to field structure
1016 * key_id <-- id of associated key
1017 * s <-- structure associated with key
1018 *
1019 * returns:
1020 * 0 in case of success, > 1 in case of error
1021 *----------------------------------------------------------------------------*/
1022
1023int
1025 int key_id,
1026 void *s);
1027
1028/*----------------------------------------------------------------------------
1029 * Return a structure for a given key associated with a field.
1030 *
1031 * If the key id is not valid, or the value type or field category is not
1032 * compatible, a fatal error is provoked.
1033 *
1034 * parameters:
1035 * f <-- pointer to field structure
1036 * key_id <-- id of associated key
1037 * s <-- structure associated with key
1038 *
1039 * returns:
1040 * pointer to structure associated with the key id for this field
1041 * (same as s)
1042 *----------------------------------------------------------------------------*/
1043
1044const void *
1046 int key_id,
1047 void *s);
1048
1049/*----------------------------------------------------------------------------*/
1050/*
1051 * \brief Return a pointer to a simple structure for a given key to a field.
1052 *
1053 * If the key id is not valid, the value type or field category is not
1054 * compatible, or the structure has been locked, a fatal error is provoked.
1055 *
1056 * Note that using this function marks the field's value for this structure
1057 * as set, and if no values have been set yet, the structure is set to
1058 * default values.
1059 *
1060 * \param[in] f pointer to field structure
1061 * \param[in] key_id id of associated key
1062 *
1063 * \return pointer to key structure in case of success,
1064 * nullptr in case of error
1065 */
1066/*----------------------------------------------------------------------------*/
1067
1068void *
1070 int key_id);
1071
1072/*----------------------------------------------------------------------------*/
1073/*
1074 * \brief Return a read-only pointer to a simple structure for a given key
1075 * to a field.
1076 *
1077 * If the key id is not valid, the value type or field category is not
1078 * compatible, a fatal error is provoked.
1079 *
1080 * \param[in] f pointer to field structure
1081 * \param[in] key_id id of associated key
1082 *
1083 * \return pointer to key structure in case of success,
1084 * nullptr in case of error
1085 */
1086/*----------------------------------------------------------------------------*/
1087
1088const void *
1090 int key_id);
1091
1092/*----------------------------------------------------------------------------
1093 * Print info relative to all field definitions to log file.
1094 *----------------------------------------------------------------------------*/
1095
1096void
1097cs_field_log_defs(void);
1098
1099/*----------------------------------------------------------------------------
1100 * Print info relative to a given field to log file.
1101 *
1102 * parameters:
1103 * f <-- pointer to field structure
1104 * log_keywords <-- log level for keywords (0: do not log,
1105 * 1: log non-default values, 2: log all)
1106 *----------------------------------------------------------------------------*/
1107
1108void
1110 int log_keywords);
1111
1112/*----------------------------------------------------------------------------
1113 * Print info relative to all defined fields to log file.
1114 *
1115 * parameters:
1116 * log_keywords <-- log level for keywords (0: do not log,
1117 * 1: log non-default values, 2: log all)
1118 *----------------------------------------------------------------------------*/
1119
1120void
1121cs_field_log_fields(int log_keywords);
1122
1123/*----------------------------------------------------------------------------
1124 * Print info relative to all key definitions to log file.
1125 *----------------------------------------------------------------------------*/
1126
1127void
1129
1130/*----------------------------------------------------------------------------
1131 * Print info relative to a given field key to log file.
1132 *
1133 * parameters:
1134 * int key_id <-- id of associated key
1135 * log_defaults <-- if true, log default field values in addition to
1136 * defined field values
1137 *----------------------------------------------------------------------------*/
1138
1139void
1140cs_field_log_key_vals(int key_id,
1141 bool log_defaults);
1142
1143/*----------------------------------------------------------------------------
1144 * Print info relative to all given field keys to log file.
1145 *
1146 * parameters:
1147 * log_defaults <-- if true, log default field values in addition to
1148 * defined field values
1149 *----------------------------------------------------------------------------*/
1150
1151void
1152cs_field_log_all_key_vals(bool log_defaults);
1153
1154/*----------------------------------------------------------------------------
1155 * Define base keys.
1156 *
1157 * Keys defined by this function are:
1158 * "label" (string)
1159 * "log" (integer)
1160 * "post_vis" (integer)
1161 * "coupled" (integer, restricted to CS_FIELD_VARIABLE)
1162 * "moment_id" (integer, restricted to
1163 * CS_FIELD_ACCUMULATOR | CS_FIELD_POSTPROCESS);
1164 *
1165 * A recommened practice for different submodules would be to use
1166 * "cs_<module>_key_init() functions to define keys specific to those modules.
1167 *----------------------------------------------------------------------------*/
1168
1169void
1171
1172/*----------------------------------------------------------------------------
1173 * Return a label associated with a field.
1174 *
1175 * If the "label" key has been set for this field, its associated string
1176 * is returned. Otherwise, the field's name is returned.
1177 *
1178 * parameters:
1179 * f <-- pointer to field structure
1180 *
1181 * returns:
1182 * pointer to character string associated with label for this field
1183 *----------------------------------------------------------------------------*/
1184
1185const char *
1187
1188/*----------------------------------------------------------------------------*/
1189
1191
1192#endif /* __CS_FIELD_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:542
double cs_real_t
Floating-point value.
Definition: cs_defs.h:342
#define END_C_DECLS
Definition: cs_defs.h:543
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.cpp:3227
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.cpp:3377
void cs_field_bc_coeffs_init(cs_field_bc_coeffs_t *bc_coeffs)
Definition: cs_field.cpp:1501
void cs_field_init_bc_coeffs(cs_field_t *f)
Initialize boundary condition coefficients arrays.
Definition: cs_field.cpp:2069
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.cpp:2836
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.cpp:3275
int cs_field_key_flag(int key_id)
Get the type flag associated with a given key id.
Definition: cs_field.cpp:3073
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.cpp:3851
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.cpp:1767
cs_field_t * cs_field_by_name(const char *name)
Return a pointer to a field based on its name.
Definition: cs_field.cpp:2489
cs_field_t * cs_field_by_double_composite_name_try(const char *name_part_1, const char *name_part_2, const char *name_part_3)
Return pointer to a field based on a double composite name if present.
Definition: cs_field.cpp:2621
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.cpp:2910
void cs_field_set_values(cs_field_t *f, cs_real_t c)
Set current field values to the given constant.
Definition: cs_field.cpp:2288
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.cpp:2539
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.cpp:3772
void cs_field_destroy_all_keys(void)
Destroy all defined field keys and associated values.
Definition: cs_field.cpp:3041
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.cpp:1613
int cs_field_n_fields(void)
Return the number of defined fields.
Definition: cs_field.cpp:1593
void cs_field_log_defs(void)
Print info relative to all field definitions to log file.
Definition: cs_field.cpp:3910
const char * cs_field_get_label(const cs_field_t *f)
Return a label associated with a field.
Definition: cs_field.cpp:4578
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.cpp:3150
void cs_field_allocate_values(cs_field_t *f)
Allocate arrays for field values.
Definition: cs_field.cpp:1828
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.cpp: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.cpp:3525
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.cpp:3646
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
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.cpp:3577
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.cpp:3119
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.cpp:2515
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.cpp:3346
void cs_field_key_disable_setup_log(int key_id)
Disable logging setup values associated with a given key.
Definition: cs_field.cpp:3097
int cs_field_define_sub_key(const char *name, int parent_id)
Define a sub key.
Definition: cs_field.cpp:3015
void cs_field_allocate_or_map_all(void)
Allocate arrays for all defined fields based on their location.
Definition: cs_field.cpp:2434
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.cpp:1556
void cs_field_destroy_all(void)
Destroy all defined fields.
Definition: cs_field.cpp: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.cpp:1859
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.cpp:1650
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.cpp:3698
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.cpp:4048
void cs_field_log_key_defs(void)
Print info relative to all key definitions to log file.
Definition: cs_field.cpp:4243
cs_field_t * cs_field_by_id(int id)
Return a pointer to a field based on its id.
Definition: cs_field.cpp:2465
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.cpp:3455
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.cpp:2962
int cs_field_key_id(const char *name)
Return an id associated with a given key name.
Definition: cs_field.cpp:2781
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.cpp:2873
void cs_field_define_keys_base(void)
Define base keys.
Definition: cs_field.cpp:4552
int cs_field_key_id_try(const char *name)
Return an id associated with a given key name if present.
Definition: cs_field.cpp:2808
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.cpp:1707
void cs_field_log_fields(int log_keywords)
Print info relative to all defined fields to log file.
Definition: cs_field.cpp:4182
void cs_field_current_to_previous(cs_field_t *f)
Copy current field values to previous values if applicable.
Definition: cs_field.cpp: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.cpp:4521
int cs_field_lock_key(cs_field_t *f, int key_id)
Lock a field relative to a given key.
Definition: cs_field.cpp:3182
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.cpp:2570
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.cpp: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.cpp:2692
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.cpp:3407
int cs_field_id_by_name(const char *name)
Return the id of a defined field based on its name.
Definition: cs_field.cpp:2671
void() cs_field_log_key_struct_t(const void *t)
Definition: cs_field.h:178
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.cpp: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.cpp:4397
@ t
Definition: cs_field_pointer.h:94
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