1 #ifndef __CS_GWF_SOIL_H__ 2 #define __CS_GWF_SOIL_H__ 3 4 /*============================================================================ 5 * Set of main functions to handle soils in the groundwater flow module 6 * when using CDO schemes 7 *============================================================================*/ 8 9 /* 10 This file is part of Code_Saturne, a general-purpose CFD tool. 11 12 Copyright (C) 1998-2021 EDF S.A. 13 14 This program is free software; you can redistribute it and/or modify it under 15 the terms of the GNU General Public License as published by the Free Software 16 Foundation; either version 2 of the License, or (at your option) any later 17 version. 18 19 This program is distributed in the hope that it will be useful, but WITHOUT 20 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 21 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 22 details. 23 24 You should have received a copy of the GNU General Public License along with 25 this program; if not, write to the Free Software Foundation, Inc., 51 Franklin 26 Street, Fifth Floor, Boston, MA 02110-1301, USA. 27 */ 28 29 /*----------------------------------------------------------------------------*/ 30 31 /*---------------------------------------------------------------------------- 32 * Local headers 33 *----------------------------------------------------------------------------*/ 34 35 #include "cs_base.h" 36 #include "cs_cdo_connect.h" 37 #include "cs_cdo_quantities.h" 38 #include "cs_mesh.h" 39 #include "cs_property.h" 40 #include "cs_volume_zone.h" 41 42 /*----------------------------------------------------------------------------*/ 43 44 BEGIN_C_DECLS 45 46 /*============================================================================ 47 * Macro definitions 48 *============================================================================*/ 49 50 /*============================================================================ 51 * Public function pointer prototypes 52 *============================================================================*/ 53 54 /*----------------------------------------------------------------------------*/ 55 /*! 56 * \brief Generic function to update the physical properties related to a 57 * hydraulic model. The soil context depends on the type of soil. 58 * 59 * \param[in] t_eval time at which one performs the evaluation 60 * \param[in] mesh pointer to a cs_mesh_t structure 61 * \param[in] connect pointer to a cs_cdo_connect_t structure 62 * \param[in] quant pointer to a cs_cdo_quantities_t structure 63 * \param[in] zone pointer to a cs_zone_t 64 * \param[in, out] soil_context pointer to a structure cast on-the-fly 65 */ 66 /*----------------------------------------------------------------------------*/ 67 68 typedef void 69 (cs_gwf_soil_update_t) (const cs_real_t t_eval, 70 const cs_mesh_t *mesh, 71 const cs_cdo_connect_t *connect, 72 const cs_cdo_quantities_t *quant, 73 const cs_zone_t *zone, 74 void *soil_context); 75 76 /*----------------------------------------------------------------------------*/ 77 /*! 78 * \brief Generic function to set free the soil context of a soil structure 79 * 80 * \param[in, out] context double pointer to a structure cast on-the-fly 81 */ 82 /*----------------------------------------------------------------------------*/ 83 84 typedef void 85 (cs_gwf_soil_free_context_t)(void **p_context); 86 87 /*============================================================================ 88 * Type definitions 89 *============================================================================*/ 90 91 /*! \enum cs_gwf_soil_hydraulic_model_t 92 * 93 * \brief Predefined hydraulic model of soils used in the groundwater flow 94 * module 95 * 96 * \var CS_GWF_SOIL_GENUCHTEN 97 * Van Genuchten-Mualem laws defining the evolution of the effective liquid 98 * saturne (also called dimensionless moisture content) and the relative 99 * permeability 100 * 101 * The (effective) liquid saturation (also called moisture content) follows the 102 * identity: 103 * S_l,eff = (S_l - theta_r)/(theta_s - theta_r) 104 * = (1 + |alpha . h|^n)^(-m) 105 * 106 * The isotropic relative permeability is defined as: 107 * k_r = S_l,eff^L * (1 - (1 - S_l,eff^(1/m))^m))^2 108 * where m = 1 - 1/n 109 * 110 * \var CS_GWF_SOIL_SATURATED 111 * Hydraulic model of soild where the soil is considered as saturated. In this 112 * model, there no evolution taken into account. The liquid saturation and the 113 * permeability are considered as constant. 114 * 115 * \var CS_GWF_SOIL_USER 116 * User-defined model of soil 117 */ 118 119 typedef enum { 120 121 CS_GWF_SOIL_GENUCHTEN, 122 CS_GWF_SOIL_SATURATED, 123 CS_GWF_SOIL_USER, 124 125 CS_GWF_SOIL_N_HYDRAULIC_MODELS 126 127 } cs_gwf_soil_hydraulic_model_t; 128 129 /*! \struct cs_gwf_soil_context_genuchten_t 130 * 131 * \brief Structure to handle the Van Genuchten-Mualen model of soil 132 * 133 * See \ref CS_GWF_SOIL_GENUCHTEN). This structure stores the parameters 134 * defining the evolution laws for the liquid saturation and the 135 * relative permeability. 136 */ 137 138 typedef struct { 139 140 /*! 141 *@name Model parameters 142 *@{ 143 * 144 * \var saturated_moisture 145 * Value of the liquid saturation (or moisture content) 146 * 147 * \var residual_moisture 148 * Also called residual liquid saturation 149 * 150 * \var saturated_permeability 151 * Permeability value (isotropic or anisotropic) when the soil is saturated 152 * 153 * \var n 154 * Shape parameter. Should be 1.25 < n < 6 155 * 156 * \var m 157 * Value depending of that of n 158 * m = 1 - 1/n 159 * 160 * \var scale 161 * Value of a scaling parameter in [m^-1] 162 * 163 * \var tortuosity 164 * tortuosity param. for saturated hydraulic conductivity 165 * 166 *@} 167 */ 168 169 double residual_moisture; 170 double saturated_moisture; 171 double saturated_permeability[3][3]; 172 173 double n; 174 double m; 175 double scale; 176 double tortuosity; 177 178 /*! 179 *@name Array values 180 *{ 181 */ 182 183 cs_real_t *permeability_values; 184 cs_real_t *head_values; 185 cs_real_t *moisture_values; 186 cs_real_t *capacity_values; 187 188 /*! 189 *@} 190 */ 191 192 } cs_gwf_soil_context_genuchten_t; 193 194 195 /*! \struct cs_gwf_soil_context_saturated_t 196 * 197 * \brief Parameters defining a saturated soil in a given zone 198 * 199 * \var saturated_moisture 200 * Value of the liquid saturation (or moisture content) 201 * 202 * \var saturated_permeability 203 * Value of the permeability in the soil 204 */ 205 206 typedef struct { 207 208 double saturated_moisture; 209 double saturated_permeability[3][3]; 210 211 } cs_gwf_soil_context_saturated_t; 212 213 214 /*! \struct cs_gwf_soil_t 215 * 216 * \brief Main structure to handle a soil in the groundawater flow module. 217 * Store a set of parameters and pointers describing a soil 218 * 219 */ 220 221 typedef struct { 222 223 /*! 224 * \var id 225 * id associated to a soil. Position in the array of soils. 226 * 227 * \var zone_id 228 * id related to a volumic cs_zone_t structure (based on cells) 229 * 230 * \var bulk_density 231 * Value of the mass density of the soil 232 * 233 * \var saturated_moisture 234 * Value of the liquid saturation (or moisture content) 235 * 236 * \var model 237 * Type of model describing the hydraulic behaviour of a soil (cf. \ref 238 * \cs_gwf_soil_hydraulic_model_t for more details) 239 * 240 * \var context 241 * Pointer to an context structure which depends on the model. This pointer has 242 * to be casted on-the-fly. 243 * 244 * \var update_properties 245 * Pointer to a function which manages the update of the properties describing 246 * the porous media or used in associated equations (diffusion terms for 247 * instance). These functions depend on the model of soil and the type of model 248 * used in the groundwater flow module. May be set to NULL if there is no need 249 * to update soil properties. 250 * 251 * \var free_context 252 * Pointer to a function which free the context structure if needed. May be set 253 * to NULL if there is nothing to free inside the context structure. 254 */ 255 256 int id; 257 int zone_id; 258 259 double bulk_density; 260 double saturated_moisture; 261 262 cs_gwf_soil_hydraulic_model_t model; 263 264 void *context; 265 266 /* Pointers to functions */ 267 268 cs_gwf_soil_update_t *update_properties; 269 cs_gwf_soil_free_context_t *free_context; 270 271 } cs_gwf_soil_t; 272 273 /*============================================================================ 274 * User-defined function prototypes 275 *============================================================================*/ 276 277 /*============================================================================ 278 * Public function prototypes 279 *============================================================================*/ 280 281 /*----------------------------------------------------------------------------*/ 282 /*! 283 * \brief Get the number of allocated soils 284 * 285 * \return the number of allocated soils 286 */ 287 /*----------------------------------------------------------------------------*/ 288 289 int 290 cs_gwf_get_n_soils(void); 291 292 /*----------------------------------------------------------------------------*/ 293 /*! 294 * \brief Retrieve a soil structure from its id 295 * 296 * \param[in] id id to look for 297 * 298 * \return a pointer to a cs_gwf_soil_t structure 299 */ 300 /*----------------------------------------------------------------------------*/ 301 302 cs_gwf_soil_t * 303 cs_gwf_soil_by_id(int id); 304 305 /*----------------------------------------------------------------------------*/ 306 /*! 307 * \brief Retrieve a soil structure from its name 308 * 309 * \param[in] name name to look for 310 * 311 * \return a pointer to a cs_gwf_soil_t structure 312 */ 313 /*----------------------------------------------------------------------------*/ 314 315 cs_gwf_soil_t * 316 cs_gwf_soil_by_name(const char *name); 317 318 /*----------------------------------------------------------------------------*/ 319 /*! 320 * \brief Get the saturated moisture for the given soil id 321 * 322 * \param[in] soil_id id of the requested soil 323 * 324 * \return the value of the saturated moisture 325 */ 326 /*----------------------------------------------------------------------------*/ 327 328 cs_real_t 329 cs_gwf_soil_get_saturated_moisture(int soil_id); 330 331 /*----------------------------------------------------------------------------*/ 332 /*! 333 * \brief Check if all soils have been set as CS_GWF_SOIL_SATURATED 334 * 335 * \return true or false 336 */ 337 /*----------------------------------------------------------------------------*/ 338 339 bool 340 cs_gwf_soil_all_saturated(void); 341 342 /*----------------------------------------------------------------------------*/ 343 /*! 344 * \brief Check that at least one soil has been defined and the model of soil 345 * exists. 346 * Raise an error if a problem is encoutered. 347 */ 348 /*----------------------------------------------------------------------------*/ 349 350 void 351 cs_gwf_soil_check(void); 352 353 /*----------------------------------------------------------------------------*/ 354 /*! 355 * \brief Create a new cs_gwf_soil_t structure and add it to the array of 356 * soils. An initialization by default of all members is performed. 357 * 358 * \param[in] zone pointer to a volume zone structure 359 * \param[in] model type of modelling for the hydraulic behavior 360 * \param[in] perm_type type of permeability (iso/anisotropic) 361 * \param[in] saturated_moisture moisture content 362 * \param[in] bulk_density value of the mass density 363 * 364 * \return a pointer to the new allocated structure 365 */ 366 /*----------------------------------------------------------------------------*/ 367 368 cs_gwf_soil_t * 369 cs_gwf_soil_create(const cs_zone_t *zone, 370 cs_gwf_soil_hydraulic_model_t model, 371 cs_property_type_t perm_type, 372 double saturated_moisture, 373 double bulk_density); 374 375 /*----------------------------------------------------------------------------*/ 376 /*! 377 * \brief Build an array storing the associated soil for each cell 378 * 379 * \param[in] n_cells number of cells 380 */ 381 /*----------------------------------------------------------------------------*/ 382 383 void 384 cs_gwf_build_cell2soil(cs_lnum_t n_cells); 385 386 /*----------------------------------------------------------------------------*/ 387 /*! 388 * \brief Get the array storing the associated soil for each cell 389 */ 390 /*----------------------------------------------------------------------------*/ 391 392 const short int * 393 cs_gwf_get_cell2soil(void); 394 395 /*----------------------------------------------------------------------------*/ 396 /*! 397 * \brief Free all cs_gwf_soil_t structures 398 */ 399 /*----------------------------------------------------------------------------*/ 400 401 void 402 cs_gwf_soil_free_all(void); 403 404 /*----------------------------------------------------------------------------*/ 405 /*! 406 * \brief Summary of the settings related to all cs_gwf_soil_t structures 407 */ 408 /*----------------------------------------------------------------------------*/ 409 410 void 411 cs_gwf_soil_log_setup(void); 412 413 /*----------------------------------------------------------------------------*/ 414 /*! 415 * \brief Set a soil defined by a saturated hydraulic model and attached to 416 * an isotropic permeability 417 * 418 * \param[in, out] soil pointer to a cs_gwf_soil_t structure 419 * \param[in] k_s value of the saturated permeability 420 */ 421 /*----------------------------------------------------------------------------*/ 422 423 void 424 cs_gwf_soil_set_iso_saturated(cs_gwf_soil_t *soil, 425 double k_s); 426 427 /*----------------------------------------------------------------------------*/ 428 /*! 429 * \brief Set a soil defined by a saturated hydraulic model and attached to 430 * an anisotropic permeability 431 * 432 * \param[in, out] soil pointer to a cs_gwf_soil_t structure 433 * \param[in] k_s value of the anisotropic saturated permeability 434 */ 435 /*----------------------------------------------------------------------------*/ 436 437 void 438 cs_gwf_soil_set_aniso_saturated(cs_gwf_soil_t *soil, 439 double k_s[3][3]); 440 441 /*----------------------------------------------------------------------------*/ 442 /*! 443 * \brief Set a soil defined by a Van Genuchten-Mualen hydraulic model and 444 * attached to an isotropic saturated permeability 445 * 446 * The (effective) liquid saturation (also called moisture content) 447 * follows the identity 448 * S_l,eff = (S_l - theta_r)/(theta_s - theta_r) 449 * = (1 + |alpha . h|^n)^(-m) 450 * 451 * The isotropic relative permeability is defined as: 452 * k_r = S_l,eff^L * (1 - (1 - S_l,eff^(1/m))^m))^2 453 * where m = 1 - 1/n 454 * 455 * \param[in, out] soil pointer to a cs_gwf_soil_t structure 456 * \param[in] k_s value of the isotropic saturated permeability 457 * \param[in] theta_r residual moisture 458 * \param[in] alpha scale parameter (in m^-1) 459 * \param[in] n shape parameter 460 * \param[in] L turtuosity parameter 461 */ 462 /*----------------------------------------------------------------------------*/ 463 464 void 465 cs_gwf_soil_set_iso_genuchten(cs_gwf_soil_t *soil, 466 double k_s, 467 double theta_r, 468 double alpha, 469 double n, 470 double L); 471 472 /*----------------------------------------------------------------------------*/ 473 /*! 474 * \brief Set a soil defined by a Van Genuchten-Mualen hydraulic model and 475 * attached to an anisotropic saturated permeability. 476 * 477 * The (effective) liquid saturation (also called moisture content) 478 * follows the identity 479 * S_l,eff = (S_l - theta_r)/(theta_s - theta_r) 480 * = (1 + |alpha . h|^n)^(-m) 481 * 482 * The isotropic relative permeability is defined as: 483 * k_r = S_l,eff^L * (1 - (1 - S_l,eff^(1/m))^m))^2 484 * where m = 1 - 1/n 485 * 486 * \param[in, out] soil pointer to a cs_gwf_soil_t structure 487 * \param[in] k_s value of the isotropic saturated permeability 488 * \param[in] theta_r residual moisture/liquid saturation 489 * \param[in] alpha scale parameter (in m^-1) 490 * \param[in] n shape parameter 491 * \param[in] L turtuosity parameter 492 */ 493 /*----------------------------------------------------------------------------*/ 494 495 void 496 cs_gwf_soil_set_aniso_genuchten(cs_gwf_soil_t *soil, 497 double k_s[3][3], 498 double theta_r, 499 double alpha, 500 double n, 501 double L); 502 503 /*----------------------------------------------------------------------------*/ 504 /*! 505 * \brief Set a soil defined by a user-defined hydraulic model 506 * 507 * \param[in, out] soil pointer to a cs_gwf_soil_t structure 508 * \param[in] context pointer to a structure cast on-the-fly 509 * \param[in] update_func function pointer to update propoerties 510 * \param[in] free_context_func function pointer to free the context 511 */ 512 /*----------------------------------------------------------------------------*/ 513 514 void 515 cs_gwf_soil_set_user(cs_gwf_soil_t *soil, 516 void *context, 517 cs_gwf_soil_update_t *update_func, 518 cs_gwf_soil_free_context_t *free_context_func); 519 520 /*----------------------------------------------------------------------------*/ 521 /*! 522 * \brief Set the properties of the groundwater flow module in the case where 523 * all soils are considered as saturated. 524 * 525 * \param[in, out] permeability pointer to a cs_property_t structure 526 * \param[in, out] moisture_content pointer to a cs_property_t structure 527 */ 528 /*----------------------------------------------------------------------------*/ 529 530 void 531 cs_gwf_soil_saturated_set_properties(cs_property_t *permeability, 532 cs_property_t *moisture_content); 533 534 /*----------------------------------------------------------------------------*/ 535 /*! 536 * \brief Set the different arrays used in soil context for a GWF model set 537 * to unsaturated single-phase flows in a porous media. 538 * 539 * \param[in] head pointer to the current head values in cells 540 * \param[in] permeability pointer to the current permeability values 541 * \param[in] moisture_content pointer to the current moisture content values 542 * \param[in] capacity pointer to the current soil capacity values 543 */ 544 /*----------------------------------------------------------------------------*/ 545 546 void 547 cs_gwf_soil_uspf_set_arrays(cs_real_t head[], 548 cs_real_t permeability[], 549 cs_real_t moisture_content[], 550 cs_real_t capacity[]); 551 552 /*----------------------------------------------------------------------------*/ 553 /*! 554 * \brief Update the soil properties 555 * 556 * \param[in] time_eval time at which one evaluates properties 557 * \param[in] mesh pointer to the mesh structure 558 * \param[in] connect pointer to the cdo connectivity 559 * \param[in] quant pointer to the cdo quantities 560 */ 561 /*----------------------------------------------------------------------------*/ 562 563 void 564 cs_gwf_soil_update(cs_real_t time_eval, 565 const cs_mesh_t *mesh, 566 const cs_cdo_connect_t *connect, 567 const cs_cdo_quantities_t *quant); 568 569 /*----------------------------------------------------------------------------*/ 570 571 END_C_DECLS 572 573 #endif /* __CS_GWF_SOIL_H__ */ 574