1 #ifndef __CS_MESH_LOCATION_H__ 2 #define __CS_MESH_LOCATION_H__ 3 4 /*============================================================================ 5 * Mesh locations management. 6 *============================================================================*/ 7 8 /* 9 This file is part of the Code_Saturne Kernel, element of the 10 Code_Saturne CFD tool. 11 12 Copyright (C) 1998-2021 EDF S.A., France 13 14 contact: saturne-support@edf.fr 15 16 The Code_Saturne Kernel is free software; you can redistribute it 17 and/or modify it under the terms of the GNU General Public License 18 as published by the Free Software Foundation; either version 2 of 19 the License, or (at your option) any later version. 20 21 The Code_Saturne Kernel is distributed in the hope that it will be 22 useful, but WITHOUT ANY WARRANTY; without even the implied warranty 23 of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 24 GNU General Public License for more details. 25 26 You should have received a copy of the GNU General Public License 27 along with the Code_Saturne Kernel; if not, write to the 28 Free Software Foundation, Inc., 29 51 Franklin St, Fifth Floor, 30 Boston, MA 02110-1301 USA 31 */ 32 33 /*----------------------------------------------------------------------------*/ 34 35 #if defined(HAVE_MPI) 36 #include <mpi.h> 37 #endif 38 39 /*---------------------------------------------------------------------------- 40 * Local headers 41 *----------------------------------------------------------------------------*/ 42 43 #include "cs_defs.h" 44 #include "cs_mesh.h" 45 46 /*----------------------------------------------------------------------------*/ 47 48 BEGIN_C_DECLS 49 50 /*============================================================================= 51 * Macro definitions 52 *============================================================================*/ 53 54 /*============================================================================ 55 * Type definitions 56 *============================================================================*/ 57 58 /* Mesh location types */ 59 60 typedef enum { 61 62 CS_MESH_LOCATION_NONE, 63 CS_MESH_LOCATION_CELLS, 64 CS_MESH_LOCATION_INTERIOR_FACES, 65 CS_MESH_LOCATION_BOUNDARY_FACES, 66 CS_MESH_LOCATION_VERTICES, 67 CS_MESH_LOCATION_FACES, 68 CS_MESH_LOCATION_EDGES, 69 CS_MESH_LOCATION_PARTICLES, 70 CS_MESH_LOCATION_OTHER 71 72 } cs_mesh_location_type_t; 73 74 /* Mesh location construction method type */ 75 76 typedef enum { 77 78 CS_MESH_LOCATION_DEF_NONE, 79 CS_MESH_LOCATION_DEF_SELECTION_STR, 80 CS_MESH_LOCATION_DEF_SELECTION_FUNC, 81 CS_MESH_LOCATION_DEF_UNION 82 83 } cs_mesh_location_def_t; 84 85 /* Opaque mesh location object */ 86 87 typedef struct _cs_mesh_location_t cs_mesh_location_t; 88 89 /*---------------------------------------------------------------------------- 90 * Function pointer to mesh location elements selection definition. 91 * 92 * If non-empty and not containing all elements, a list of elements 93 * of the parent mesh belonging to the location should be allocated 94 * (using BFT_MALLOC) and defined by this function when called. 95 * This list's lifecycle is then managed by the mesh location object. 96 * 97 * Note: if the input pointer is non-NULL, it must point to valid data 98 * when the selection function is called, so that value or structure should 99 * not be temporary (i.e. local); 100 * 101 * parameters: 102 * input <-- pointer to optional (untyped) value or structure. 103 * m <-- pointer to associated mesh structure. 104 * location_id <-- id of associated location. 105 * n_elts --> number of selected elements 106 * elt_ids --> list of selected elements (0 to n-1 numbering). 107 *----------------------------------------------------------------------------*/ 108 109 typedef void 110 (cs_mesh_location_select_t) (void *input, 111 const cs_mesh_t *m, 112 int location_id, 113 cs_lnum_t *n_elts, 114 cs_lnum_t **elt_ids); 115 116 /*============================================================================= 117 * Global variables 118 *============================================================================*/ 119 120 /* Names associated with location types */ 121 122 extern const char *cs_mesh_location_type_name[]; 123 124 /*============================================================================= 125 * Public function prototypes 126 *============================================================================*/ 127 128 /*---------------------------------------------------------------------------- 129 * Return number of mesh locations defined. 130 *----------------------------------------------------------------------------*/ 131 132 int 133 cs_mesh_location_n_locations(void); 134 135 /*---------------------------------------------------------------------------- 136 * Initialize mesh location API. 137 * 138 * By default, 7 mesh locations are built, matching the 7 first values of 139 * the cs_mesh_location_type_t enum: CS_MESH_LOCATION_NONE for global 140 * values, CS_MESH_LOCATION_CELLS for the cells of the (default) global mesh, 141 * CS_MESH_LOCATION_INTERIOR_FACES and CS_MESH_LOCATION_BOUNDARY_FACES for 142 * its faces, and CS_MESH_LOCATION_VERTICES for its vertices. 143 * CS_MESH_LOCATION_FACES and a placeholder for CS_MESH_LOCATION_EDGES are 144 * also added for CDO discretizations. 145 * 146 * Locations should then be built once the global mesh is complete, and 147 * its halo structures completed. 148 *----------------------------------------------------------------------------*/ 149 150 void 151 cs_mesh_location_initialize(void); 152 153 /*---------------------------------------------------------------------------- 154 * Finalize mesh location API. 155 *----------------------------------------------------------------------------*/ 156 157 void 158 cs_mesh_location_finalize(void); 159 160 /*----------------------------------------------------------------------------*/ 161 /*! 162 * \brief Find the related location id from the location name 163 * 164 * \param[in] ref_name name of the location to find 165 * 166 * \return -1 if not found otherwise the associated id 167 */ 168 /*----------------------------------------------------------------------------*/ 169 170 int 171 cs_mesh_location_get_id_by_name(const char *ref_name); 172 173 /*---------------------------------------------------------------------------- 174 * Associate mesh locations with a mesh. 175 * 176 * If mesh_id is negative, all defined mesh locations are associated 177 * (which is useful for the common case where only one mesh is present). 178 * If mesh_id is non-negative, only the location with the matching 179 * id is associated (which may be useful when multiple meshes are defined). 180 * 181 * The number of elements are computed based on the underlying mesh, 182 * and element lists are built for mesh subset locations. 183 * 184 * parameters: 185 * mesh <-- pointer to associated mesh structure 186 * id <-- id of mesh location 187 *----------------------------------------------------------------------------*/ 188 189 void 190 cs_mesh_location_build(cs_mesh_t *mesh, 191 int id); 192 193 /*---------------------------------------------------------------------------- 194 * Define a new mesh location. 195 * 196 * So as to define a subset of mesh entities of a given type, an optional 197 * selection criteria may be given. 198 * 199 * parameters: 200 * name <-- name of location to define 201 * type <-- type of location to define 202 * criteria <-- selection criteria for associated elements, or NULL 203 * 204 * returns: 205 * id of newly created mesh location 206 *----------------------------------------------------------------------------*/ 207 208 int 209 cs_mesh_location_add(const char *name, 210 cs_mesh_location_type_t type, 211 const char *criteria); 212 213 /*----------------------------------------------------------------------------*/ 214 /*! 215 * \brief Define a new mesh location with an associated selection function. 216 * 217 * So as to define a subset of mesh entities of a given type, a pointer 218 * to a selection function may be given. 219 * 220 * This requires more programming but allows finer control than selection 221 * criteria, as the function has access to the complete mesh structure. 222 * 223 * \param[in] name name of location to define 224 * \param[in] type type of location to define 225 * \param[in] func pointer to selection function for associated 226 * elements, or NULL 227 * \param[in, out] input pointer to optional (untyped) value 228 * or structure. 229 * 230 * \return id of newly defined created mesh location 231 */ 232 /*----------------------------------------------------------------------------*/ 233 234 int 235 cs_mesh_location_add_by_func(const char *name, 236 cs_mesh_location_type_t type, 237 cs_mesh_location_select_t *func, 238 void *input); 239 240 /*----------------------------------------------------------------------------*/ 241 /*! 242 * \brief Define a new mesh location. 243 * 244 * So as to define a subset of mesh entities of a given type, a list of ids 245 * related to existing mesh locations may be given 246 * 247 * \param[in] name name of location to define 248 * \param[in] type type of location to define 249 * \param[in] n_ml_ids number of mesh location ids 250 * \param[in] ml_ids list of mesh location ids 251 * \param[in] complement take the complement of the selected entities if true 252 * 253 * \return id of newly created mesh location 254 */ 255 /*----------------------------------------------------------------------------*/ 256 257 int 258 cs_mesh_location_add_by_union(const char *name, 259 cs_mesh_location_type_t type, 260 int n_ml_ids, 261 const int *ml_ids, 262 bool complement); 263 264 /*---------------------------------------------------------------------------- 265 * Get a mesh location's name. 266 * 267 * parameters: 268 * id <-- id of mesh location 269 * 270 * returns: 271 * pointer to mesh location name 272 *----------------------------------------------------------------------------*/ 273 274 const char * 275 cs_mesh_location_get_name(int id); 276 277 /*---------------------------------------------------------------------------- 278 * Get a mesh location's type. 279 * 280 * parameters: 281 * id <-- id of mesh location 282 * 283 * returns: 284 * mesh location type 285 *----------------------------------------------------------------------------*/ 286 287 cs_mesh_location_type_t 288 cs_mesh_location_get_type(int id); 289 290 /*---------------------------------------------------------------------------- 291 * Get a mesh location's number of elements. 292 * 293 * A pointer to a array of 3 values is returned: 294 * 0: local number of elements 295 * 1: with standard ghost elements (if applicable) 296 * 2: with extended ghost elements (if applicable) 297 * 298 * parameters: 299 * id <-- id of mesh location 300 * 301 * returns: 302 * array of numbers of elements. 303 *----------------------------------------------------------------------------*/ 304 305 const cs_lnum_t * 306 cs_mesh_location_get_n_elts(int id); 307 308 /*---------------------------------------------------------------------------- 309 * Get a mesh location's elements list, if present. 310 * 311 * A list of elements is defined if the location is a subset of a main 312 * location type. 313 * 314 * \deprecated Use \ref cs_mesh_location_get_elt_ids_try or 315 * \ref cs_mesh_location_get_elt_ids instead. 316 * 317 * parameters: 318 * id <-- id of mesh location 319 * 320 * returns: 321 * pointer to elements list (0 to n-1 numbering). 322 *----------------------------------------------------------------------------*/ 323 324 const cs_lnum_t * 325 cs_mesh_location_get_elt_list(int id); 326 327 /*----------------------------------------------------------------------------*/ 328 /*! 329 * \brief Get a mesh location's element ids, if present. 330 * 331 * An array of element ids is returned if the location is a subset of a main 332 * main location type, and NULL is returned when the id array would map to 333 * the identity function (i.e. {0, 1, 2, ..., n_elts-1}). 334 * 335 * \param[in] id id of mesh location 336 * 337 * \return pointer to elements array (0 to n-1 numbering). 338 */ 339 /*----------------------------------------------------------------------------*/ 340 341 const cs_lnum_t * 342 cs_mesh_location_get_elt_ids_try(int id); 343 344 /*----------------------------------------------------------------------------*/ 345 /*! 346 * \brief Get a mesh location's element ids. 347 * 348 * This function may only be used with a given location if 349 * \ref cs_mesh_location_set_explicit_ids has been used to indicate 350 * explicit ids are needed for this location. 351 * 352 * \param[in] id id of mesh location 353 * 354 * \return pointer to elements array (0 to n-1 numbering). 355 */ 356 /*----------------------------------------------------------------------------*/ 357 358 const cs_lnum_t * 359 cs_mesh_location_get_elt_ids(int id); 360 361 /*----------------------------------------------------------------------------*/ 362 /*! 363 * \brief Get a mesh location's definition method. 364 * 365 * \param[in] id id of mesh location 366 * 367 * \return enum value corresponding to the definition method 368 */ 369 /*----------------------------------------------------------------------------*/ 370 371 cs_mesh_location_def_t 372 cs_mesh_location_get_definition_method(int id); 373 374 /*----------------------------------------------------------------------------*/ 375 /*! 376 * \brief Get a mesh location's selection criteria string 377 * 378 * \param[in] id id of mesh location 379 * 380 * \return pointer to mesh location selection criteria, or NULL 381 */ 382 /*----------------------------------------------------------------------------*/ 383 384 const char * 385 cs_mesh_location_get_selection_string(int id); 386 387 /*----------------------------------------------------------------------------*/ 388 /*! 389 * \brief Get a mesh location's selection function pointer 390 * 391 * \param[in] id id of mesh location 392 * 393 * \return pointer to mesh location selection function pointer, or NULL 394 */ 395 /*----------------------------------------------------------------------------*/ 396 397 cs_mesh_location_select_t * 398 cs_mesh_location_get_selection_function(int id); 399 400 /*----------------------------------------------------------------------------*/ 401 /*! 402 * \brief Get a mesh location's number of sub ids 403 * 404 * \param[in] id id of mesh location 405 * 406 * \return integer value equal to the number of sub ids 407 */ 408 /*----------------------------------------------------------------------------*/ 409 410 int 411 cs_mesh_location_get_n_sub_ids(int id); 412 413 /*----------------------------------------------------------------------------*/ 414 /*! 415 * \brief Get a mesh location's list of sub ids. 416 * 417 * \param[in] id id of mesh location 418 * 419 * \return pointer to the list of sub ids. 420 */ 421 /*----------------------------------------------------------------------------*/ 422 423 int * 424 cs_mesh_location_get_sub_ids(int id); 425 426 /*----------------------------------------------------------------------------*/ 427 /*! 428 * \brief Check if a mesh location is built as a complement of other mesh 429 * locations. 430 * 431 * \param[in] id id of mesh location 432 * 433 * \return true if build method is a complement, false otherwise. 434 */ 435 /*----------------------------------------------------------------------------*/ 436 437 bool 438 cs_mesh_location_is_complement(int id); 439 440 /*----------------------------------------------------------------------------*/ 441 /*! 442 * \brief Check if \ref cs_mesh_location_get_elt_ids always returns 443 * explicit element ids for a given mesh location. 444 * 445 * \param[in] id id or type of mesh location 446 * 447 * \return true if explicit element ids are required, false otherwise 448 */ 449 /*----------------------------------------------------------------------------*/ 450 451 bool 452 cs_mesh_location_get_explicit_ids(int id); 453 454 /*----------------------------------------------------------------------------*/ 455 /*! 456 * \brief Set behavior of \ref cs_mesh_location_get_elt_ids for a given 457 * mesh location and locations based on it. 458 * 459 * \param[in] id id or type of mesh location 460 * \param[in] explicit_elt_ids indicate if explicit element ids are required 461 */ 462 /*----------------------------------------------------------------------------*/ 463 464 void 465 cs_mesh_location_set_explicit_ids(int id, 466 bool explicit_elt_ids); 467 468 /*----------------------------------------------------------------------------*/ 469 470 END_C_DECLS 471 472 #endif /* __CS_MESH_LOCATION_H__ */ 473