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