1 #ifndef __CS_EQUATION_PRIV_H__ 2 #define __CS_EQUATION_PRIV_H__ 3 4 /*============================================================================ 5 * Functions to handle cs_equation_t structure and its related structures 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 * Local headers 30 *----------------------------------------------------------------------------*/ 31 32 #include "cs_equation_param.h" 33 #include "cs_equation_common.h" 34 #include "cs_field.h" 35 #include "cs_restart.h" 36 37 /*----------------------------------------------------------------------------*/ 38 39 BEGIN_C_DECLS 40 41 /*============================================================================ 42 * Macro definitions 43 *============================================================================*/ 44 45 /*============================================================================ 46 * Type definitions 47 *============================================================================*/ 48 49 /*---------------------------------------------------------------------------- 50 * Function pointer types 51 *----------------------------------------------------------------------------*/ 52 53 /*----------------------------------------------------------------------------*/ 54 /*! 55 * \brief Initialize a scheme data structure used during the building of the 56 * algebraic system 57 * 58 * \param[in] eqp pointer to a \ref cs_equation_param_t structure 59 * \param[in] var_id id of the variable field 60 * \param[in] bflux_id id of the boundary flux field 61 * \param[in, out] eqb pointer to a \ref cs_equation_builder_t struct. 62 * 63 * \return a pointer to a new allocated scheme context structure 64 */ 65 /*----------------------------------------------------------------------------*/ 66 67 typedef void * 68 (cs_equation_init_context_t)(const cs_equation_param_t *eqp, 69 int var_id, 70 int bflux_id, 71 cs_equation_builder_t *eqb); 72 73 /*----------------------------------------------------------------------------*/ 74 /*! 75 * \brief Destroy a scheme data structure 76 * 77 * \param[in, out] scheme_context pointer to a builder structure 78 * 79 * \return a NULL pointer 80 */ 81 /*----------------------------------------------------------------------------*/ 82 83 typedef void * 84 (cs_equation_free_context_t)(void *scheme_context); 85 86 /*----------------------------------------------------------------------------*/ 87 /*! 88 * \brief Initialize the variable field values related to an equation 89 * 90 * \param[in] t_eval time at which one performs the evaluation 91 * \param[in] field_id id related to the variable field of this equation 92 * \param[in] mesh pointer to a cs_mesh_t structure 93 * \param[in] eqp pointer to a cs_equation_param_t structure 94 * \param[in, out] eqb pointer to a cs_equation_builder_t structure 95 * \param[in, out] context pointer to the scheme context (cast on-the-fly) 96 */ 97 /*----------------------------------------------------------------------------*/ 98 99 typedef void 100 (cs_equation_init_values_t)(cs_real_t t_eval, 101 const int field_id, 102 const cs_mesh_t *mesh, 103 const cs_equation_param_t *eqp, 104 cs_equation_builder_t *eqb, 105 void *context); 106 107 /*----------------------------------------------------------------------------*/ 108 /*! 109 * \brief Build and solve a linear system within the CDO framework 110 * 111 * \param[in] cur2prev true="current to previous" operation is performed 112 * \param[in] mesh pointer to a \ref cs_mesh_t structure 113 * \param[in] field_id id related to the variable field of this equation 114 * \param[in] eqp pointer to a \ref cs_equation_param_t structure 115 * \param[in, out] eqb pointer to a \ref cs_equation_builder_t structure 116 * \param[in, out] eqc pointer to a scheme context structure 117 */ 118 /*----------------------------------------------------------------------------*/ 119 120 typedef void 121 (cs_equation_solve_t)(bool cur2prev, 122 const cs_mesh_t *mesh, 123 const int field_id, 124 const cs_equation_param_t *eqp, 125 cs_equation_builder_t *eqb, 126 void *eqc); 127 128 /*----------------------------------------------------------------------------*/ 129 /*! 130 * \brief Set the Dirichlet boundary stemming from the settings. 131 * 132 * \param[in] t_eval time at which one evaluates BCs 133 * \param[in] mesh pointer to a cs_mesh_t structure 134 * \param[in] eqp pointer to a cs_equation_param_t structure 135 * \param[in, out] eqb pointer to a cs_equation_builder_t structure 136 * \param[in, out] context pointer to the scheme context (cast on-the-fly) 137 * \param[in, out] field_val pointer to the values of the variable field 138 */ 139 /*----------------------------------------------------------------------------*/ 140 141 typedef void 142 (cs_equation_set_dir_bc_t)(cs_real_t t_eval, 143 const cs_mesh_t *mesh, 144 const cs_equation_param_t *eqp, 145 cs_equation_builder_t *eqb, 146 void *context, 147 cs_real_t field_val[]); 148 149 /*----------------------------------------------------------------------------*/ 150 /*! 151 * \brief Create the matrix of the current algebraic system. 152 * Allocate and initialize the right-hand side associated to the given 153 * builder structure 154 * 155 * \param[in] eqp pointer to a cs_equation_param_t structure 156 * \param[in, out] eqb pointer to a cs_equation_builder_t structure 157 * \param[in, out] data pointer to generic data structure 158 * \param[in, out] system_matrix pointer of pointer to a cs_matrix_t struct. 159 * \param[in, out] system_rhs pointer of pointer to an array of double 160 */ 161 /*----------------------------------------------------------------------------*/ 162 163 typedef void 164 (cs_equation_initialize_system_t)(const cs_equation_param_t *eqp, 165 cs_equation_builder_t *eqb, 166 void *data, 167 cs_matrix_t **system_matrix, 168 cs_real_t **system_rhs); 169 170 /*----------------------------------------------------------------------------*/ 171 /*! 172 * \brief Build a linear system within the CDO framework 173 * 174 * \param[in] m pointer to a \ref cs_mesh_t structure 175 * \param[in] field_val pointer to the current value of the field 176 * \param[in] eqp pointer to a \ref cs_equation_param_t structure 177 * \param[in, out] eqb pointer to a \ref cs_equation_builder_t structure 178 * \param[in, out] data pointer to a scheme builder structure 179 * \param[in, out] rhs right-hand side to compute 180 * \param[in, out] matrix pointer to \ref cs_matrix_t structure to compute 181 */ 182 /*----------------------------------------------------------------------------*/ 183 184 typedef void 185 (cs_equation_build_system_t)(const cs_mesh_t *mesh, 186 const cs_real_t *field_val, 187 const cs_equation_param_t *eqp, 188 cs_equation_builder_t *eqb, 189 void *data, 190 cs_real_t *rhs, 191 cs_matrix_t *matrix); 192 193 /*----------------------------------------------------------------------------*/ 194 /*! 195 * \brief Carry out operations for allocating and/or initializing the solution 196 * array and the right hand side of the linear system to solve. 197 * Handle parallelism thanks to cs_range_set_t structure. 198 * 199 * \param[in, out] eq_cast pointer to generic builder structure 200 * \param[in, out] p_x pointer of pointer to the solution array 201 * \param[in, out] p_rhs pointer of pointer to the RHS array 202 */ 203 /*----------------------------------------------------------------------------*/ 204 205 typedef void 206 (cs_equation_prepare_solve_t)(void *eq_to_cast, 207 cs_real_t *p_x[], 208 cs_real_t *p_rhs[]); 209 210 /*----------------------------------------------------------------------------*/ 211 /*! 212 * \brief Store solution(s) of the linear system into a field structure 213 * Update extra-field values if required (for hybrid discretization) 214 * 215 * \param[in] solu solution array 216 * \param[in] rhs rhs associated to this solution array 217 * \param[in] eqp pointer to a \ref cs_equation_param_t structure 218 * \param[in, out] eqb pointer to a \ref cs_equation_builder_t structure 219 * \param[in, out] data pointer to a data structure 220 * \param[in, out] field_val pointer to the current value of the field 221 */ 222 /*----------------------------------------------------------------------------*/ 223 224 typedef void 225 (cs_equation_update_field_t)(const cs_real_t *solu, 226 const cs_real_t *rhs, 227 const cs_equation_param_t *eqp, 228 cs_equation_builder_t *eqb, 229 void *data, 230 cs_real_t *field_val); 231 232 /*----------------------------------------------------------------------------*/ 233 /*! 234 * \brief Compute the balance for an equation over the full computational 235 * domain between time t_cur and t_cur + dt_cur 236 * 237 * \param[in] eqp pointer to a \ref cs_equation_param_t 238 * \param[in, out] eqb pointer to a \ref cs_equation_builder_t 239 * \param[in, out] context pointer to a scheme context structure 240 * 241 * \return a pointer to a cs_equation_balance_t structure 242 */ 243 /*----------------------------------------------------------------------------*/ 244 245 typedef cs_equation_balance_t * 246 (cs_equation_get_balance_t)(const cs_equation_param_t *eqp, 247 cs_equation_builder_t *eqb, 248 void *context); 249 250 /*----------------------------------------------------------------------------*/ 251 /*! 252 * \brief Generic prototype for extra-operations related to an equation 253 * 254 * \param[in] eqp pointer to a cs_equation_param_t structure 255 * \param[in, out] eqb pointer to a cs_equation_builder_t structure 256 * \param[in, out] context pointer to a generic data structure 257 */ 258 /*----------------------------------------------------------------------------*/ 259 260 typedef void 261 (cs_equation_extra_op_t)(const cs_equation_param_t *eqp, 262 cs_equation_builder_t *eqb, 263 void *context); 264 265 /*----------------------------------------------------------------------------*/ 266 /*! 267 * \brief Retrieve cellwise structure including work buffers used to build 268 * a CDO system cellwise. Generic prototype for all CDO schemes. 269 * 270 * \param[out] csys pointer to a pointer on a cs_cell_sys_t structure 271 * \param[out] cb pointer to a pointer on a cs_cell_builder_t structure 272 */ 273 /*----------------------------------------------------------------------------*/ 274 275 typedef void 276 (cs_equation_get_builders_t)(cs_cell_sys_t **csys, 277 cs_cell_builder_t **cb); 278 279 /*----------------------------------------------------------------------------*/ 280 /*! 281 * \brief Compute or retrieve an array of values at a given mesh location 282 * Currently, vertices, cells or faces are possible locations 283 * The lifecycle of this array is managed by the code. So one does not 284 * have to free the return pointer. 285 * 286 * \param[in, out] scheme_context pointer to a data structure cast on-the-fly 287 * \param[in] previous retrieve the previous state (true/false) 288 * 289 * \return a pointer to an array of \ref cs_real_t 290 */ 291 /*----------------------------------------------------------------------------*/ 292 293 typedef cs_real_t * 294 (cs_equation_get_values_t)(void *scheme_context, 295 bool previous); 296 297 /*----------------------------------------------------------------------------*/ 298 /*! 299 * \brief Generic prototype dedicated to read or write additional arrays (not 300 * defined as fields) useful for the checkpoint/restart process 301 * 302 * \param[in, out] restart pointer to \ref cs_restart_t structure 303 * \param[in] eqname name of the related equation 304 * \param[in, out] scheme_context pointer to a data structure cast on-the-fly 305 */ 306 /*----------------------------------------------------------------------------*/ 307 308 typedef void 309 (cs_equation_restart_t)(cs_restart_t *restart, 310 const char *eqname, 311 void *scheme_context); 312 313 /*---------------------------------------------------------------------------- 314 * Structure type 315 *----------------------------------------------------------------------------*/ 316 317 /*! \struct cs_equation_t 318 * \brief Main structure to handle the discretization and the resolution of 319 * an equation. 320 * 321 */ 322 323 struct _cs_equation_t { 324 325 int id; 326 327 cs_equation_param_t *param; /* Set of parameters related to an equation */ 328 329 /* Variable attached to this equation is defined as a cs_field_t structure */ 330 char *restrict varname; 331 int field_id; 332 int boundary_flux_id; 333 334 /* Algebraic system */ 335 /* ---------------- */ 336 337 /* There can be two different sizes for the linear system to handle 338 - One for "scatter"-type operations based on the number of geometrical 339 entities owned by the local instance of the mesh 340 - One for "gather"-type operations based on a balance of the number of 341 DoFs from a algebraic point of view. In parallel runs, these two sizes 342 can be different. 343 n_sles_gather_elts <= n_sles_scatter_elts 344 */ 345 346 cs_lnum_t n_sles_scatter_elts; 347 cs_lnum_t n_sles_gather_elts; 348 349 /* Right-hand side defined by a local cellwise building. This may be 350 different from the rhs given to cs_sles_solve() in parallel mode. */ 351 cs_real_t *rhs; 352 353 /* Matrix to inverse with cs_sles_solve() The matrix size can be different 354 from the rhs size in parallel mode since the decomposition is different */ 355 cs_matrix_t *matrix; 356 357 /* Range set to handle parallelism. Shared with cs_cdo_connect_t struct.*/ 358 const cs_range_set_t *rset; 359 360 /* \var builder 361 * Common members for building the algebraic system between the numerical 362 * schemes 363 */ 364 cs_equation_builder_t *builder; 365 366 /* Data depending on the numerical scheme (cast on-the-fly) */ 367 void *scheme_context; 368 369 /* Pointer to functions (see prototypes just above) */ 370 cs_equation_init_context_t *init_context; 371 cs_equation_free_context_t *free_context; 372 373 cs_equation_init_values_t *init_field_values; 374 cs_equation_solve_t *solve_steady_state; 375 cs_equation_solve_t *solve; 376 377 cs_equation_get_balance_t *compute_balance; 378 cs_equation_extra_op_t *postprocess; 379 cs_equation_extra_op_t *current_to_previous; 380 381 cs_equation_restart_t *read_restart; 382 cs_equation_restart_t *write_restart; 383 384 cs_equation_get_values_t *get_cell_values; 385 cs_equation_get_values_t *get_face_values; 386 cs_equation_get_values_t *get_edge_values; 387 cs_equation_get_values_t *get_vertex_values; 388 389 cs_equation_get_builders_t *get_cw_build_structures; 390 391 /* Deprecated functions --> use rather solve() and solve_steady_state() */ 392 /* -------------------- */ 393 cs_equation_initialize_system_t *initialize_system; 394 cs_equation_set_dir_bc_t *set_dir_bc; 395 cs_equation_build_system_t *build_system; 396 cs_equation_prepare_solve_t *prepare_solving; 397 cs_equation_update_field_t *update_field; 398 399 /* Timer statistic for a coarse profiling */ 400 int main_ts_id; /* Id of the main timer stats for this equation */ 401 402 }; 403 404 /*============================================================================ 405 * Public function prototypes 406 *============================================================================*/ 407 408 409 /*----------------------------------------------------------------------------*/ 410 411 END_C_DECLS 412 413 #endif /* __CS_EQUATION_PRIV_H__ */ 414