/usr/include/p4est_extended.h is in libp4est-dev 1.1-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 | /*
This file is part of p4est.
p4est is a C library to manage a collection (a forest) of multiple
connected adaptive quadtrees or octrees in parallel.
Copyright (C) 2010 The University of Texas System
Written by Carsten Burstedde, Lucas C. Wilcox, and Tobin Isaac
p4est is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
p4est is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with p4est; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
/********************************************************************
* IMPORTANT NOTE *
* *
* These interfaces are intended for those who like finer control. *
* The API offers extended versions of some basic p4est functions. *
* The API may change without notice. *
********************************************************************/
/** \file p4est_extended.h
*
* Interface routines with extended capabilities.
*
* \ingroup p4est
*/
#ifndef P4EST_EXTENDED_H
#define P4EST_EXTENDED_H
#include <p4est.h>
#include <p4est_mesh.h>
#include <p4est_iterate.h>
SC_EXTERN_C_BEGIN;
/** Data pertaining to selecting, inspecting, and profiling algorithms.
* A pointer to this structure is hooked into the p4est main structure.
*
*
* The balance_ranges and balance_notify* times are collected
* whenever an inspect structure is present in p4est.
*/
/* TODO: Describe the purpose of various switches, counters, and timings. */
struct p4est_inspect
{
/** Use sc_ranges to determine the asymmetric communication pattern.
* If \a use_balance_ranges is false (the default), sc_notify is used. */
int use_balance_ranges;
/** If true, call both sc_ranges and sc_notify and verify consistency.
* Which is actually used is still determined by \a use_balance_ranges. */
int use_balance_ranges_notify;
/** Verify sc_ranges and/or sc_notify as applicable. */
int use_balance_verify;
/** If positive and smaller than p4est_num ranges, overrides it */
int balance_max_ranges;
size_t balance_A_count_in;
size_t balance_A_count_out;
size_t balance_comm_sent;
size_t balance_comm_nzpeers;
size_t balance_B_count_in;
size_t balance_B_count_out;
size_t balance_zero_sends[2], balance_zero_receives[2];
double balance_A;
double balance_comm;
double balance_B;
double balance_ranges; /**< time spent in sc_ranges */
double balance_notify; /**< time spent in sc_notify */
/** time spent in sc_notify_allgather */
double balance_notify_allgather;
int use_B;
};
/** Callback function prototype to replace one set of quadrants with another.
*
* This is used by extended routines when the quadrants of an existing, valid
* p4est are changed. The callback allows the user to make changes to newly
* initialized quadrants before the quadrants that they replace are destroyed.
*
* \param [in] num_outgoing The number of outgoing quadrants.
* \param [in] outgoing The outgoing quadrants: after the callback, the
* user_data, if \a p4est->data_size is nonzero,
* will be destroyed.
* \param [in] num_incoming The number of incoming quadrants.
* \param [in,out] incoming The incoming quadrants: prior to the callback,
* the user_data, if \a p4est->data_size is nonzero,
* is allocated, and the p4est_init_t callback,
* if it has been provided, will be called.
*
* If the mesh is being refined, num_outgoing will be 1 and num_incoming will
* be 4, and vice versa if the mesh is being coarsened.
*/
typedef void (*p4est_replace_t) (p4est_t * p4est,
p4est_topidx_t which_tree,
int num_outgoing,
p4est_quadrant_t * outgoing[],
int num_incoming,
p4est_quadrant_t * incoming[]);
/** Create a new forest.
* This is a more general form of p4est_new.
* See the documentation of p4est_new for basic usage.
*
* \param [in] min_quadrants Minimum initial quadrants per processor.
* Makes the refinement pattern mpisize-specific.
* \param [in] min_level The forest is refined at least to this level.
* May be negative or 0, then it has no effect.
* \param [in] fill_uniform If true, fill the forest with a uniform mesh
* instead of the coarsest possible one.
* The latter is partition-specific so that
* is usually not a good idea.
*/
p4est_t *p4est_new_ext (sc_MPI_Comm mpicomm,
p4est_connectivity_t * connectivity,
p4est_locidx_t min_quadrants,
int min_level, int fill_uniform,
size_t data_size, p4est_init_t init_fn,
void *user_pointer);
/** Create a new mesh.
* \param [in] p4est A forest that is fully 2:1 balanced.
* \param [in] ghost The ghost layer created from the
* provided p4est.
* \param [in] compute_tree_index Boolean to decide whether to allocate and
* compute the quad_to_tree list.
* \param [in] compute_level_lists Boolean to decide whether to compute the
* level lists in quad_level.
* \param [in] btype Currently ignored, only face neighbors
* are stored.
* \return A fully allocated mesh structure.
*/
p4est_mesh_t *p4est_mesh_new_ext (p4est_t * p4est,
p4est_ghost_t * ghost,
int compute_tree_index,
int compute_level_lists,
p4est_connect_type_t btype);
/** Refine a forest with a bounded refinement level and a replace option.
* \param [in,out] p4est The forest is changed in place.
* \param [in] refine_recursive Boolean to decide on recursive refinement.
* \param [in] maxlevel Maximum allowed refinement level (inclusive).
* If this is negative the level is restricted only
* by the compile-time constant QMAXLEVEL in p4est.h.
* \param [in] refine_fn Callback function that must return true if a quadrant
* shall be refined. If refine_recursive is true,
* refine_fn is called for every existing and newly
* created quadrant. Otherwise, it is called for every
* existing quadrant. It is possible that a refinement
* request made by the callback is ignored. To catch
* this case, you can examine whether init_fn or
* replace_fn gets called.
* \param [in] init_fn Callback function to initialize the user_data for
* newly created quadrants, which is guaranteed to be
* allocated. This function pointer may be NULL.
* \param [in] replace_fn Callback function that allows the user to change
* incoming quadrants based on the quadrants they
* replace; may be NULL.
*/
void p4est_refine_ext (p4est_t * p4est,
int refine_recursive, int maxlevel,
p4est_refine_t refine_fn,
p4est_init_t init_fn,
p4est_replace_t replace_fn);
/** Coarsen a forest.
* \param [in,out] p4est The forest is changed in place.
* \param [in] coarsen_recursive Boolean to decide on recursive coarsening.
* \param [in] callback_orphans Boolean to enable calling coarsen_fn even on
* non-families. In this case, the second quadrant
* pointer in the argument list of the callback is NULL,
* subsequent pointers are undefined, and the return
* value is ignored. If coarsen_recursive is true, it
* is possible that a quadrant is called once or more as
* an orphan and eventually becomes part of a family.
* \param [in] coarsen_fn Callback function that returns true if a
* family of quadrants shall be coarsened.
* \param [in] init_fn Callback function to initialize the user_data
* which is already allocated automatically.
* \param [in] replace_fn Callback function that allows the user to change
* incoming quadrants based on the quadrants they
* replace.
*/
void p4est_coarsen_ext (p4est_t * p4est, int coarsen_recursive,
int callback_orphans,
p4est_coarsen_t coarsen_fn,
p4est_init_t init_fn,
p4est_replace_t replace_fn);
/** 2:1 balance the size differences of neighboring elements in a forest.
* \param [in,out] p4est The p4est to be worked on.
* \param [in] btype Balance type (face or corner/full).
* Corner balance is almost never required when
* discretizing a PDE; just causes smoother mesh grading.
* \param [in] init_fn Callback function to initialize the user_data
* which is already allocated automatically.
* \param [in] replace_fn Callback function that allows the user to change
* incoming quadrants based on the quadrants they
* replace.
*/
void p4est_balance_ext (p4est_t * p4est,
p4est_connect_type_t btype,
p4est_init_t init_fn,
p4est_replace_t replace_fn);
void p4est_balance_subtree_ext (p4est_t * p4est,
p4est_connect_type_t btype,
p4est_topidx_t which_tree,
p4est_init_t init_fn,
p4est_replace_t replace_fn);
/** Repartition the forest.
*
* The forest is partitioned between processors such that each processor
* has an approximately equal number of quadrants (or weight).
*
* \param [in,out] p4est The forest that will be partitioned.
* \param [in] partition_for_coarsening If true, the partition
* is modified to allow one level of coarsening.
* \param [in] weight_fn A weighting function or NULL
* for uniform partitioning.
* \return The global number of shipped quadrants
*/
p4est_gloidx_t p4est_partition_ext (p4est_t * p4est,
int partition_for_coarsening,
p4est_weight_t weight_fn);
/** p4est_iterate_ext adds the option \a remote: if this is false, then it is
* the same as p4est_iterate; if this is true, then corner callbacks are also
* called on corners for hanging faces touched by local quadrants.
*/
void p4est_iterate_ext (p4est_t * p4est,
p4est_ghost_t * ghost_layer,
void *user_data,
p4est_iter_volume_t iter_volume,
p4est_iter_face_t iter_face,
p4est_iter_corner_t iter_corner,
int remote);
/** Save the complete connectivity/p4est data to disk. This is a collective
* operation that all MPI processes need to call. All processes write
* into the same file, so the filename given needs to be identical over
* all parallel invocations.
* See p4est_load_ext for information on the autopartition parameter.
* \param [in] filename Name of the file to write.
* \param [in] p4est Valid forest structure.
* \param [in] save_data If true, the element data is saved.
* Otherwise, a data size of 0 is saved.
* \param [in] save_partition If false, save file as if 1 core was used.
* If true, save core count and partition.
* Advantage: Partition can be recovered on loading
* with same mpisize and autopartition false.
* Disadvantage: Makes the file depend on mpisize.
* Either way the file can be loaded with autopartition true.
* \note Aborts on file errors.
*/
void p4est_save_ext (const char *filename, p4est_t * p4est,
int save_data, int save_partition);
/** Load the complete connectivity/p4est structure from disk.
* It is possible to load the file with a different number of processors
* than has been used to write it. The partition will then be uniform.
* \param [in] filename Name of the file to read.
* \param [in] mpicomm A valid MPI communicator.
* \param [in] data_size Size of data for each quadrant which can be
* zero. Then user_data_pool is set to NULL.
* If data_size is zero, load_data is ignored.
* \param [in] load_data If true, the element data is loaded. This is
* only permitted if the saved data size matches.
* If false, the stored data size is ignored.
* \param [in] autopartition Ignore saved partition and make it uniform.
* \param [in] broadcasthead Have only rank 0 read headers and bcast them.
* \param [in] user_pointer Assign to the user_pointer member of the p4est
* before init_fn is called the first time.
* \param [out] connectivity Connectivity must be destroyed separately.
* \return Returns a valid forest structure. A pointer to a valid
* connectivity structure is returned through the last
* argument.
* \note Aborts on file errors or invalid file contents.
*/
p4est_t *p4est_load_ext (const char *filename, sc_MPI_Comm mpicomm,
size_t data_size, int load_data,
int autopartition, int broadcasthead,
void *user_pointer,
p4est_connectivity_t ** connectivity);
/** The same as p4est_load_ext, but reading the connectivity/p4est from an
* open sc_io_source_t stream.
*/
p4est_t *p4est_source_ext (sc_io_source_t * src,
sc_MPI_Comm mpicomm, size_t data_size,
int load_data, int autopartition,
int broadcasthead, void *user_pointer,
p4est_connectivity_t ** connectivity);
SC_EXTERN_C_END;
#endif /* !P4EST_EXTENDED_H */
|