programmer's documentation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
fvm_writer_helper.h
Go to the documentation of this file.
1 #ifndef __FVM_WRITER_HELPER_H__
2 #define __FVM_WRITER_HELPER_H__
3 
4 /*============================================================================
5  * Helper types and functions for mesh and field writers
6  *============================================================================*/
7 
8 /*
9  This file is part of Code_Saturne, a general-purpose CFD tool.
10 
11  Copyright (C) 1998-2013 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 #include "cs_defs.h"
31 
32 /*----------------------------------------------------------------------------
33  * Local headers
34  *----------------------------------------------------------------------------*/
35 
36 #include "fvm_defs.h"
37 #include "fvm_gather.h"
38 #include "fvm_nodal.h"
39 #include "fvm_writer.h"
40 
41 /*----------------------------------------------------------------------------*/
42 
44 
45 /*=============================================================================
46  * Macro definitions
47  *============================================================================*/
48 
49 /*============================================================================
50  * Type definitions
51  *============================================================================*/
52 
53 /*----------------------------------------------------------------------------
54  * FVM nodal to writer section translation list
55  *----------------------------------------------------------------------------*/
56 
57 typedef struct _fvm_writer_section_t {
58 
59  struct _fvm_writer_section_t *next; /* Pointer to next element
60  in list (NULL at end) */
61 
62  const fvm_nodal_section_t *section; /* Corresponding section in mesh */
63 
64  cs_gnum_t extra_vertex_base; /* Start global number of added
65  vertices (for tesselation) */
66 
67  cs_lnum_t num_shift; /* Element number shift when no
68  parent lists are used */
69  fvm_element_t type; /* Corresponding element type (may
70  differ from section->type when
71  using tesselations) */
72 
73  _Bool continues_previous; /* Indicates if the corresponding FVM
74  nodal section should be appended
75  to the previous one on output */
76 
78 
79 /*----------------------------------------------------------------------------
80  * FVM nodal to writer field output helper
81  *----------------------------------------------------------------------------*/
82 
83 /*
84  Pointer to structure keeping track of the status of a writer's field
85  output state. The structure itself is private, and is defined in fvm_writer.c
86 */
87 
88 typedef struct _fvm_writer_field_helper_t fvm_writer_field_helper_t;
89 
90 /*=============================================================================
91  * Semi-private function prototypes
92  *============================================================================*/
93 
94 /*----------------------------------------------------------------------------
95  * Build list of sections to output
96  *
97  * Depending on whether multiple sections of a given element type
98  * are allowed or not, sections may be ordered in different ways.
99  * Discarded element types are not added to the list.
100  *
101  * parameters:
102  * mesh <-- pointer to nodal mesh structure
103  * group_same_type <-- group sections of the same type
104  * min_export_dim <-- minimum dimension of sections to export
105  * discard_polygons <-- ignore polygonal sections
106  * discard_polyhedra <-- ignore polyhedral sections
107  * divide_polygons <-- tesselate polygonal sections
108  * divide_polyhedra <-- tesselate polyhedral sections
109  *
110  * returns:
111  * array of section translations (must be freed by caller),
112  * or NULL if section list is completely empty
113  *----------------------------------------------------------------------------*/
114 
116 fvm_writer_export_list(const fvm_nodal_t *mesh,
117  int min_export_dim,
118  _Bool group_same_type,
119  _Bool discard_polygons,
120  _Bool discard_polyhedra,
121  _Bool divide_polygons,
122  _Bool divide_polyhedra);
123 
124 /*----------------------------------------------------------------------------
125  * Create field writer helper structure.
126  *
127  * Local values are initialized, ang lobal values are set to zero
128  * (they may be initialized by calling fvm_writer_field_helper_init_g()).
129  *
130  * parameters:
131  * mesh <-- pointer to nodal mesh structure
132  * section_list <-- point to export section list helper structure
133  * field_dim <-- indicates output field dimension
134  * interlace <-- indicates if output is interlaced
135  * location <-- indicates if field is cell or node based
136  * datatype <-- datatype of destination buffers
137  *
138  * returns:
139  * pointer to allocated and initialized field writer helper
140  *----------------------------------------------------------------------------*/
141 
142 fvm_writer_field_helper_t *
143 fvm_writer_field_helper_create(const fvm_nodal_t *mesh,
144  const fvm_writer_section_t *section_list,
145  int field_dim,
146  cs_interlace_t interlace,
147  cs_datatype_t datatype,
148  fvm_writer_var_loc_t location);
149 
150 /*----------------------------------------------------------------------------
151  * Destroy FVM field writer helper.
152  *
153  * parameters:
154  * helper <-> pointer to structure that should be destroyed
155  *
156  * returns:
157  * NULL pointer
158  *----------------------------------------------------------------------------*/
159 
160 fvm_writer_field_helper_t *
161 fvm_writer_field_helper_destroy(fvm_writer_field_helper_t *helper);
162 
163 #if defined(HAVE_MPI)
164 
165 /*----------------------------------------------------------------------------
166  * Initialize global values for an fvm_writer_field_helper structure.
167  *
168  * Internal buffers for gathering of data to rank 0 of the given
169  * communicator are also allocated.
170  *
171  * parameters:
172  * helper <-> pointer to structure that should be initialized
173  * section_list <-- point to export section list helper structure
174  * mesh <-- pointer to nodal mesh structure
175  * comm <-- associated MPI communicator
176  *
177  * returns:
178  * pointer to allocated and initialized field writer helper
179  *----------------------------------------------------------------------------*/
180 
181 void
182 fvm_writer_field_helper_init_g(fvm_writer_field_helper_t *helper,
183  const fvm_writer_section_t *section_list,
184  const fvm_nodal_t *mesh,
185  MPI_Comm comm);
186 
187 #endif /* defined(HAVE_MPI) */
188 
189 /*----------------------------------------------------------------------------
190  * Return sizes associated with a writer field helper.
191  *
192  * parameters:
193  * helper <-- pointer to helper structure
194  * input_size --> Total field locations in input (or NULL)
195  * output_size --> Total field locations in output (or NULL)
196  * max_grouped_elements_out --> Max. field locations in a single group
197  * (elements of a given type if sections are
198  * grouped, elements of a given section
199  * otherwise; NULL if unused)
200  * min_output_buffer_size --> Minimum required buffer size (or NULL)
201  *----------------------------------------------------------------------------*/
202 
203 void
204 fvm_writer_field_helper_get_size(const fvm_writer_field_helper_t *helper,
205  size_t *input_size,
206  size_t *output_size,
207  size_t *max_grouped_elements_out,
208  size_t *min_output_buffer_size);
209 
210 /*----------------------------------------------------------------------------
211  * Return the output dimension associated with a writer field helper.
212  *
213  * parameters:
214  * helper <-- pointer to helper structure
215  *
216  * returns:
217  * field dimension associated with helper
218  *----------------------------------------------------------------------------*/
219 
220 int
221 fvm_writer_field_helper_field_dim(const fvm_writer_field_helper_t *helper);
222 
223 /*----------------------------------------------------------------------------
224  * Return the output datatype associated with a writer field helper.
225  *
226  * parameters:
227  * helper <-- pointer to helper structure
228  *
229  * returns:
230  * output datatype associated with helper
231  *----------------------------------------------------------------------------*/
232 
234 fvm_writer_field_helper_datatype(const fvm_writer_field_helper_t *helper);
235 
236 /*----------------------------------------------------------------------------
237  * Partially distribute field values to an output buffer.
238  *
239  * parameters:
240  * helper <-> pointer to helper structure
241  * export_section <-- pointer to section helper structure
242  * src_dim <-- dimension of source data
243  * src_dim_shift <-- source data dimension shift (start index)
244  * src_interlace <-- indicates if field in memory is interlaced
245  * n_parent_lists <-- indicates if field values are to be obtained
246  * directly through the local entity index (when 0) or
247  * through the parent entity numbers (when 1 or more)
248  * parent_num_shift <-- parent list to common number index shifts;
249  * size: n_parent_lists
250  * datatype <-- indicates the data type of (source) field values
251  * field_values <-- array of associated field value arrays
252  * datatype <-- input data type
253  * field_values <-- pointer to input array
254  * output_buffer <-- pointer to output buffer
255  * (working array only for ranks > 0)
256  * output_buffer_size <-- size of output buffer (in datatype units)
257  * output_size --> size of output upon return (in datatype units)
258  *
259  * returns:
260  * 0 if values were distributed to the output buffer, 1 if the end of the
261  * section has already been reached and no values were left to distribute.
262  *----------------------------------------------------------------------------*/
263 
264 int
265 fvm_writer_field_helper_step_e(fvm_writer_field_helper_t *helper,
266  const fvm_writer_section_t *export_section,
267  int src_dim,
268  int src_dim_shift,
269  cs_interlace_t src_interlace,
270  int n_parent_lists,
271  const cs_lnum_t parent_num_shift[],
272  cs_datatype_t datatype,
273  const void *const field_values[],
274  void *output_buffer,
275  size_t output_buffer_size,
276  size_t *output_size);
277 
278 /*----------------------------------------------------------------------------
279  * Partially distribute per node field values to an output buffer.
280  *
281  * parameters:
282  * helper <-> pointer to helper structure
283  * mesh <-- pointer to associated mesh
284  * src_dim <-- dimension of source data
285  * src_dim_shift <-- source data dimension shift (start index)
286  * src_interlace <-- indicates if field in memory is interlaced
287  * n_parent_lists <-- indicates if field values are to be obtained
288  * directly through the local entity index (when 0) or
289  * through the parent entity numbers (when 1 or more)
290  * parent_num_shift <-- parent list to common number index shifts;
291  * size: n_parent_lists
292  * datatype <-- indicates the data type of (source) field values
293  * field_values <-- array of associated field value arrays
294  * datatype <-- input data type
295  * field_values <-- pointer to input array
296  * output_buffer <-- pointer to output buffer
297  * (working array only for ranks > 0)
298  * output_buffer_size <-- size of output buffer (in datatype units)
299  * output_size --> size of output upon return (in datatype units)
300  *
301  * returns:
302  * 0 if values were distributed to the output buffer, 1 if the end of the
303  * section has already been reached and no values were left to distribute.
304  *----------------------------------------------------------------------------*/
305 
306 int
307 fvm_writer_field_helper_step_n(fvm_writer_field_helper_t *helper,
308  const fvm_nodal_t *mesh,
309  int src_dim,
310  int src_dim_shift,
311  cs_interlace_t src_interlace,
312  int n_parent_lists,
313  const cs_lnum_t parent_num_shift[],
314  cs_datatype_t datatype,
315  const void *const field_values[],
316  void *output_buffer,
317  size_t output_buffer_size,
318  size_t *output_size);
319 
320 /*----------------------------------------------------------------------------*/
321 
323 
324 #endif /* __FVM_WRITER_HELPER_H__ */