programmer's documentation
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
cs_post.h
Go to the documentation of this file.
1 #ifndef __CS_POST_H__
2 #define __CS_POST_H__
3 
4 /*============================================================================
5  * Post-processing management
6  *============================================================================*/
7 
8 /*
9  This file is part of Code_Saturne, a general-purpose CFD tool.
10 
11  Copyright (C) 1998-2014 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 /*----------------------------------------------------------------------------
31  * Standard C library headers
32  *----------------------------------------------------------------------------*/
33 
34 /*----------------------------------------------------------------------------
35  * Local headers
36  *----------------------------------------------------------------------------*/
37 
38 #include "fvm_nodal.h"
39 #include "fvm_writer.h"
40 
41 #include "cs_base.h"
42 #include "cs_time_step.h"
43 
44 /*----------------------------------------------------------------------------*/
45 
47 
48 /*============================================================================
49  * Macro definitions
50  *============================================================================*/
51 
52 /*
53  * Output type masks
54  */
55 
56 #define CS_POST_ON_LOCATION (1 << 0) /* postprocess variables
57  on their base location
58  (volume for variables) */
59 #define CS_POST_BOUNDARY_NR (1 << 1) /* postprocess boundary
60  without reconstruction */
61 
62 /*============================================================================
63  * Local type definitions
64  *============================================================================*/
65 
66 /* Datatype enumeration */
67 
68 typedef enum {
75 
76 /*----------------------------------------------------------------------------
77  * Function pointer to elements selection definition.
78  *
79  * Each function of this sort may be used to select a given type of element,
80  * usually cells, interior faces, boundary faces, or particles.
81  *
82  * If non-empty and not containing all elements, a list of elements of the
83  * main mesh should be allocated (using BFT_MALLOC) and defined by this
84  * function when called. This list's lifecycle is then managed by the
85  * postprocessing subsystem.
86  *
87  * Note: if the input pointer is non-NULL, it must point to valid data
88  * when the selection function is called, so either:
89  * - that value or structure should not be temporary (i.e. local);
90  * - post-processing output must be ensured using cs_post_write_meshes()
91  * with a fixed-mesh writer before the data pointed to goes out of scope;
92  *
93  * parameters:
94  * input <-> pointer to optional (untyped) value or structure.
95  * n_elts --> number of selected elements.
96  * elt_list --> list of selected elements (0 to n-1 numbering).
97  *----------------------------------------------------------------------------*/
98 
99 typedef void
100 (cs_post_elt_select_t) (void *input,
101  cs_lnum_t *n_elts,
102  cs_lnum_t **elt_list);
103 
104 /*----------------------------------------------------------------------------
105  * Function pointer associated with a specific post-processing output.
106  *
107  * Such functions are registered using the cs_post_add_time_dep_vars(),
108  * and all registered functions are automatically called by
109  * cs_post_write_vars().
110  *
111  * Note: if the input pointer is non-NULL, it must point to valid data
112  * when the output function is called, so either:
113  * - that value or structure should not be temporary (i.e. local);
114  * - post-processing output must be ensured using cs_post_write_var()
115  * or similar before the data pointed to goes out of scope.
116  *
117  * parameters:
118  * input <-> pointer to optional (untyped) value or structure.
119  * ts <-- time step status structure, or NULL
120  *----------------------------------------------------------------------------*/
121 
122 typedef void
124  const cs_time_step_t *ts);
125 
126 /*----------------------------------------------------------------------------
127  * Function pointer associated with a specific post-processing output
128  * on multiple meshes.
129  *
130  * Such functions are registered using the cs_post_add_time_mesh_dep_vars(),
131  * and all registered functions are automatically called by
132  * cs_post_write_vars().
133  *
134  * Note: if the input pointer is non-NULL, it must point to valid data
135  * when the output function is called, so either:
136  * - that value or structure should not be temporary (i.e. local);
137  * - post-processing output must be ensured using cs_post_write_var()
138  * or similar before the data pointed to goes out of scope.
139  *
140  * parameters:
141  * input <-> pointer to optional (untyped) value or structure.
142  * mesh_id <-- id of the output mesh for the current call
143  * cat_id <-- category id of the output mesh for the current call
144  * ent_flag <-- indicate global presence of cells (ent_flag[0]), interior
145  * faces (ent_flag[1]), boundary faces (ent_flag[2]),
146  * or particles (ent_flag[3])
147  * n_cells <-- local number of cells of post_mesh
148  * n_i_faces <-- local number of interior faces of post_mesh
149  * n_b_faces <-- local number of boundary faces of post_mesh
150  * cell_list <-- list of cells (1 to n) of post-processing mesh
151  * i_face_list <-- list of interior faces (1 to n) of post-processing mesh
152  * b_face_list <-- list of boundary faces (1 to n) of post-processing mesh
153  * ts <-- time step status structure, or NULL
154  *----------------------------------------------------------------------------*/
155 
156 typedef void
158  int mesh_id,
159  int cat_id,
160  int ent_flag[4],
161  cs_lnum_t n_cells,
162  cs_lnum_t n_i_faces,
163  cs_lnum_t n_b_faces,
164  const cs_lnum_t cell_list[],
165  const cs_lnum_t i_face_list[],
166  const cs_lnum_t b_face_list[],
167  const cs_time_step_t *ts);
168 
169 /*=============================================================================
170  * Global variables
171  *============================================================================*/
172 
173 /*============================================================================
174  * Public function prototypes
175  *============================================================================*/
176 
177 /*----------------------------------------------------------------------------
178  * Configure the post-processing output so that a mesh displacement field
179  * may be output automatically for meshes based on the global volume mesh/
180  *----------------------------------------------------------------------------*/
181 
182 void
184 
185 /*----------------------------------------------------------------------------
186  * Configure the post-processing output so that mesh connectivity
187  * may be automatically updated.
188  *
189  * This is done for meshes defined using selection criteria or functions.
190  * The behavior of Lagrangian meshes is unchanged.
191  *
192  * To be effective, this function should be called before defining
193  * postprocessing meshes.
194  *----------------------------------------------------------------------------*/
195 
196 void
198 
199 /*----------------------------------------------------------------------------
200  * Define a writer; this objects manages a case's name, directory, and format,
201  * as well as associated mesh's time dependency, and the default output
202  * frequency for associated variables.
203  *
204  * This function must be called before the time loop. If a writer with a
205  * given id is defined multiple times, the last definition supercedes the
206  * previous ones.
207  *
208  * parameters:
209  * writer_id <-- number of writer to create (< 0 reserved, > 0 for user)
210  * case_name <-- associated case name
211  * dir_name <-- associated directory name
212  * fmt_name <-- associated format name
213  * fmt_opts <-- associated format options string
214  * time_dep <-- FVM_WRITER_FIXED_MESH if mesh definitions are fixed,
215  * FVM_WRITER_TRANSIENT_COORDS if coordinates change,
216  * FVM_WRITER_TRANSIENT_CONNECT if connectivity changes
217  * output_at_end <-- force output at calculation end if not 0
218  * frequency_n <-- default output frequency in time-steps, or < 0
219  * frequency_t <-- default output frequency in seconds, or < 0
220  * (has priority over frequency_n)
221  *----------------------------------------------------------------------------*/
222 
223 void
224 cs_post_define_writer(int writer_id,
225  const char *case_name,
226  const char *dir_name,
227  const char *fmt_name,
228  const char *fmt_opts,
229  fvm_writer_time_dep_t time_dep,
230  bool output_at_end,
231  int frequency_n,
232  double frequency_t);
233 
234 /*----------------------------------------------------------------------------
235  * Define a volume post-processing mesh.
236  *
237  * parameters:
238  * mesh_id <-- id of mesh to define (< 0 reserved, > 0 for user)
239  * mesh_name <-- associated mesh name
240  * cell_criteria <-- selection criteria for cells
241  * add_groups <-- if true, add group information if present
242  * auto_variables <-- if true, automatic output of main variables
243  * n_writers <-- number of associated writers
244  * writer_ids <-- ids of associated writers
245  *----------------------------------------------------------------------------*/
246 
247 void
248 cs_post_define_volume_mesh(int mesh_id,
249  const char *mesh_name,
250  const char *cell_criteria,
251  bool add_groups,
252  bool auto_variables,
253  int n_writers,
254  const int writer_ids[]);
255 
256 /*----------------------------------------------------------------------------
257  * Define a volume post-processing mesh using a selection function.
258  *
259  * The selection may be updated over time steps if both the time_varying
260  * flag is set to true and the mesh is only associated with writers defined
261  * with the FVM_WRITER_TRANSIENT_CONNECT option.
262  *
263  * Note: if the cell_select_input pointer is non-NULL, it must point
264  * to valid data when the selection function is called, so either:
265  * - that value or structure should not be temporary (i.e. local);
266  * - post-processing output must be ensured using cs_post_write_meshes()
267  * with a fixed-mesh writer before the data pointed to goes out of scope;
268  *
269  * parameters:
270  * mesh_id <-- id of mesh to define (< 0 reserved, > 0 for user)
271  * mesh_name <-- associated mesh name
272  * cell_select_func <-- pointer to cells selection function
273  * cell_select_input <-> pointer to optional input data for the cell
274  * selection function, or NULL
275  * time_varying <-- if true, try to redefine mesh at each output time
276  * add_groups <-- if true, add group information if present
277  * auto_variables <-- if true, automatic output of main variables
278  * n_writers <-- number of associated writers
279  * writer_ids <-- ids of associated writers
280  *----------------------------------------------------------------------------*/
281 
282 void
284  const char *mesh_name,
285  cs_post_elt_select_t *cell_select_func,
286  void *cell_select_input,
287  bool time_varying,
288  bool add_groups,
289  bool auto_variables,
290  int n_writers,
291  const int writer_ids[]);
292 
293 /*----------------------------------------------------------------------------
294  * Define a surface post-processing mesh.
295  *
296  * parameters:
297  * mesh_id <-- id of mesh to define (< 0 reserved, > 0 for user)
298  * mesh_name <-- associated mesh name
299  * i_face_criteria <-- selection criteria for interior faces
300  * b_face_criteria <-- selection criteria for boundary faces
301  * add_groups <-- if true, add group information if present
302  * auto_variables <-- if true, automatic output of main variables
303  * n_writers <-- number of associated writers
304  * writer_ids <-- ids of associated writers
305  *----------------------------------------------------------------------------*/
306 
307 void
308 cs_post_define_surface_mesh(int mesh_id,
309  const char *mesh_name,
310  const char *i_face_criteria,
311  const char *b_face_criteria,
312  bool add_groups,
313  bool auto_variables,
314  int n_writers,
315  const int writer_ids[]);
316 
317 /*----------------------------------------------------------------------------
318  * Define a surface post-processing mesh using selection functions.
319  *
320  * The selection may be updated over time steps if both the time_varying
321  * flag is set to true and the mesh is only associated with writers defined
322  * with the FVM_WRITER_TRANSIENT_CONNECT option.
323  *
324  * Note: if i_face_select_input or b_face_select_input pointer is non-NULL,
325  * it must point to valid data when the selection function is called,
326  * so either:
327  * - that value or structure should not be temporary (i.e. local);
328  * - post-processing output must be ensured using cs_post_write_meshes()
329  * with a fixed-mesh writer before the data pointed to goes out of scope;
330  *
331  * parameters:
332  * mesh_id <-- id of mesh to define (< 0 reserved, > 0 for user)
333  * mesh_name <-- associated mesh name
334  * i_face_select_func <-- pointer to interior faces selection function
335  * b_face_select_func <-- pointer to boundary faces selection function
336  * i_face_select_input <-> pointer to optional input data for the interior
337  * faces selection function, or NULL
338  * b_face_select_input <-> pointer to optional input data for the boundary
339  * faces selection function, or NULL
340  * time_varying <-- if true, try to redefine mesh at each output time
341  * add_groups <-- if true, add group information if present
342  * auto_variables <-- if true, automatic output of main variables
343  * n_writers <-- number of associated writers
344  * writer_ids <-- ids of associated writers
345  *----------------------------------------------------------------------------*/
346 
347 void
349  const char *mesh_name,
350  cs_post_elt_select_t *i_face_select_func,
351  cs_post_elt_select_t *b_face_select_func,
352  void *i_face_select_input,
353  void *b_face_select_input,
354  bool time_varying,
355  bool add_groups,
356  bool auto_variables,
357  int n_writers,
358  const int writer_ids[]);
359 
360 /*----------------------------------------------------------------------------
361  * Define a particles post-processing mesh.
362  *
363  * Such a mesh is always time-varying, and will only be output by writers
364  * defined with the FVM_WRITER_TRANSIENT_CONNECT option.
365  *
366  * If the trajectory_mode argument is set to true, this logic is reversed,
367  * and output will only occur for writers defined with the
368  * FVM_WRITER_FIXED_MESH option. In this case, a submesh consisting of
369  * trajectory segments for the current time step will be added to
370  * the output at each output time step.
371  *
372  * parameters:
373  * mesh_id <-- id of mesh to define (< 0 reserved, > 0 for user)
374  * mesh_name <-- associated mesh name
375  * cell_criteria <-- selection criteria for cells containing particles,
376  * or NULL.
377  * density <-- fraction of the particles in the selected area
378  * which should be output (0 < density <= 1)
379  * trajectory <-- if true, activate trajectory mode
380  * auto_variables <-- if true, automatic output of main variables
381  * n_writers <-- number of associated writers
382  * writer_ids <-- ids of associated writers
383  *----------------------------------------------------------------------------*/
384 
385 void
387  const char *mesh_name,
388  const char *cell_criteria,
389  double density,
390  bool trajectory,
391  bool auto_variables,
392  int n_writers,
393  const int writer_ids[]);
394 
395 /*----------------------------------------------------------------------------
396  * Define a particles post-processing mesh using a selection function.
397  *
398  * The selection may be updated over time steps.
399  *
400  * Such a mesh is always time-varying, and will only be output by writers
401  * defined with the FVM_WRITER_TRANSIENT_CONNECT option.
402  *
403  * If the trajectory_mode argument is set to true, this logic is reversed,
404  * and output will only occur for writers defined with the
405  * FVM_WRITER_FIXED_MESH option. In this case, a submesh consisting of
406  * trajectory segments for the current time step will be added to
407  * the output at each output time step.
408  *
409  * Note: if the p_select_input pointer is non-NULL, it must point
410  * to valid data when the selection function is called, so
411  * that value or structure should not be temporary (i.e. local);
412  *
413  * parameters:
414  * mesh_id <-- id of mesh to define (< 0 reserved, > 0 for user)
415  * mesh_name <-- associated mesh name
416  * p_select_func <-- pointer to particles selection function
417  * p_select_input <-> pointer to optional input data for the particles
418  * selection function, or NULL
419  * density <-- fraction of the particles in the selected area
420  * which should be output (0 < density <= 1)
421  * trajectory <-- if true, activate trajectory mode
422  * auto_variables <-- if true, automatic output of main variables
423  * n_writers <-- number of associated writers
424  * writer_ids <-- ids of associated writers
425  *----------------------------------------------------------------------------*/
426 
427 void
429  const char *mesh_name,
430  cs_post_elt_select_t *p_select_func,
431  void *p_select_input,
432  bool trajectory,
433  bool auto_variables,
434  int n_writers,
435  const int writer_ids[]);
436 
437 /*----------------------------------------------------------------------------
438  * Create an alias to a post-processing mesh.
439  *
440  * An alias allows association of an extra identifier (id) to an
441  * existing post-processing mesh, and thus to associate different writers
442  * than those associated with the existing mesh. For example, this allows
443  * outputting a set of main variables every n1 time steps with one writer,
444  * and outputting a specific set of variables every n2 time time steps to
445  * another post-processing set using another writer, without the overhead
446  * that would be incurred by duplication of the post-processing mesh.
447  *
448  * An alias is thus treated in all points like its associated mesh;
449  * if the definition of either one is modified, that of the other is
450  * modified also.
451  *
452  * It is forbidden to associate an alias to another alias (as there is no
453  * identified use for this, and it would make consistency checking more
454  * difficult), but multiple aliases may be associated with a given mesh.
455  *
456  * parameters:
457  * mesh_id <-- id of mesh to define (< 0 reserved, > 0 for user)
458  * aliased_mesh_id <-- id of aliased mesh
459  * auto_variables <-- if true, automatic output of main variables
460  * n_writers <-- number of associated writers
461  * writer_ids <-- ids of associated writers
462  *----------------------------------------------------------------------------*/
463 
464 void
465 cs_post_define_alias_mesh(int mesh_id,
466  int aliased_mesh_id,
467  bool auto_variables,
468  int n_writers,
469  const int writer_ids[]);
470 
471 /*----------------------------------------------------------------------------
472  * Create a post-processing mesh associated with an existing exportable mesh
473  * representation.
474  *
475  * If the exportable mesh is not intended to be used elsewhere, one can choose
476  * to transfer its property to the post-processing mesh, which will then
477  * manage its lifecycle based on its own requirements.
478  *
479  * If the exportable mesh must still be shared, one must be careful to
480  * maintain consistency between this mesh and the post-processing output.
481  *
482  * The mesh in exportable dimension may be of a lower dimension than
483  * its parent mesh, if it has been projected. In this case, a
484  * dim_shift value of 1 indicates that parent cells are mapped to
485  * exportable faces, and faces to edges, while a dim_shift value of 2
486  * would indicate that parent cells are mapped to edges.
487  * This is important when variables values are exported.
488  *
489  * parameters:
490  * mesh_id <-- number of mesh to create (< 0 reserved, > 0 for user)
491  * exp_mesh <-- mesh in exportable representation (i.e. fvm_nodal_t)
492  * dim_shift <-- nonzero if exp_mesh has been projected
493  * transfer <-- if true, ownership of exp_mesh is transferred to
494  * the post-processing mesh
495  * auto_variables <-- if true, automatic output of main variables
496  * n_writers <-- number of associated writers
497  * writer_ids <-- ids of associated writers
498  *----------------------------------------------------------------------------*/
499 
500 void
501 cs_post_define_existing_mesh(int mesh_id,
502  fvm_nodal_t *exp_mesh,
503  int dim_shift,
504  bool transfer,
505  bool auto_variables,
506  int n_writers,
507  const int writer_ids[]);
508 
509 /*----------------------------------------------------------------------------
510  * Create a mesh based upon the extraction of edges from an existing mesh.
511  *
512  * The newly created edges have no link to their parent elements, so
513  * no variable referencing parent elements may be output to this mesh,
514  * whose main use is to visualize "true" face edges when polygonal faces
515  * are subdivided by the writer. In this way, even highly non-convex
516  * faces may be visualized correctly if their edges are overlaid on
517  * the surface mesh with subdivided polygons.
518  *
519  * parameters:
520  * mesh_id <-- id of edges mesh to create (< 0 reserved, > 0 for user)
521  * base_mesh_id <-- id of existing mesh (< 0 reserved, > 0 for user)
522  * n_writers <-- number of associated writers
523  * writer_ids <-- ids of associated writers
524  *----------------------------------------------------------------------------*/
525 
526 void
527 cs_post_define_edges_mesh(int mesh_id,
528  int base_mesh_id,
529  int n_writers,
530  const int writer_ids[]);
531 
532 /*----------------------------------------------------------------------------
533  * Get a postprocessing meshes entity presence flag.
534  *
535  * This flag is an array of 3 integers, indicating the presence of elements
536  * of given types on at least one subdomain (i.e. rank):
537  * 0: presence of cells
538  * 1: presence of interior faces
539  * 2: presence of boundary faces
540  *
541  * parameters:
542  * mesh_id <-- postprocessing mesh id
543  *
544  * returns:
545  * pointer to entity presence flag
546  *----------------------------------------------------------------------------*/
547 
548 const int *
549 cs_post_mesh_get_ent_flag(int mesh_id);
550 
551 /*----------------------------------------------------------------------------
552  * Get a postprocessing mesh's number of cells.
553  *
554  * parameters:
555  * mesh_id <-- postprocessing mesh id
556  *
557  * returns:
558  * number of cells of postprocessing mesh.
559  *----------------------------------------------------------------------------*/
560 
561 cs_lnum_t
562 cs_post_mesh_get_n_cells(int mesh_id);
563 
564 /*----------------------------------------------------------------------------
565  * Get a postprocessing mesh's list of cells.
566  *
567  * The array of cell ids must be of at least size
568  * cs_post_mesh_get_n_cells(mesh_id).
569  *
570  * parameters:
571  * mesh_id <-- postprocessing mesh id
572  * cell_ids --> array of associated cell ids (0 to n-1 numbering,
573  * relative to main mesh)
574  *----------------------------------------------------------------------------*/
575 
576 void
577 cs_post_mesh_get_cell_ids(int mesh_id,
578  cs_lnum_t *cell_ids);
579 
580 /*----------------------------------------------------------------------------
581  * Get a postprocessing mesh's number of interior faces.
582  *
583  * parameters:
584  * mesh_id <-- postprocessing mesh id
585  *
586  * returns:
587  * number of cells of postprocessing mesh.
588  *----------------------------------------------------------------------------*/
589 
590 cs_lnum_t
591 cs_post_mesh_get_n_i_faces(int mesh_id);
592 
593 /*----------------------------------------------------------------------------
594  * Get a postprocessing mesh's list of boundary faces.
595  *
596  * The array of boundary face ids must be of at least size
597  * cs_post_mesh_get_n_b_faces(mesh_id).
598  *
599  * parameters:
600  * mesh_id <-- postprocessing mesh id
601  * i_face_ids --> array of associated interior faces ids
602  * (0 to n-1 numbering, relative to main mesh)
603  *----------------------------------------------------------------------------*/
604 
605 void
606 cs_post_mesh_get_i_face_ids(int mesh_id,
607  cs_lnum_t i_face_ids[]);
608 
609 /*----------------------------------------------------------------------------
610  * Get a postprocessing mesh's number of boundary faces
611  *
612  * parameters:
613  * mesh_id <-- postprocessing mesh id
614  *
615  * returns:
616  * number of cells of postprocessing mesh.
617  *----------------------------------------------------------------------------*/
618 
619 cs_lnum_t
620 cs_post_mesh_get_n_b_faces(int mesh_id);
621 
622 /*----------------------------------------------------------------------------
623  * Get a postprocessing mesh's list of boundary faces.
624  *
625  * The array of boundary face ids must be of at least size
626  * cs_post_mesh_get_n_b_faces(mesh_id).
627  *
628  * parameters:
629  * mesh_id <-- postprocessing mesh id
630  * b_face_ids --> array of associated boundary faces ids
631  * (0 to n-1 numbering, relative to main mesh)
632  *----------------------------------------------------------------------------*/
633 
634 void
635 cs_post_mesh_get_b_face_ids(int mesh_id,
636  cs_lnum_t b_face_ids[]);
637 
638 /*----------------------------------------------------------------------------
639  * Remove a post-processing mesh.
640  *
641  * No further post-processing output will be allowed on this mesh,
642  * so the associated structures may be freed.
643  *
644  * A post-processing mesh that has been associated with a time-varying
645  * writer or that is referenced by an alias may not be removed.
646  *
647  * parameters:
648  * mesh_id <-- id of mesh to remove
649  *----------------------------------------------------------------------------*/
650 
651 void
652 cs_post_free_mesh(int mesh_id);
653 
654 /*----------------------------------------------------------------------------
655  * Check for the existence of a writer of the given id.
656  *
657  * parameters:
658  * writer_id <-- writer id to check
659  *
660  * returns:
661  * true if writer with this id exists, false otherwise
662  *----------------------------------------------------------------------------*/
663 
664 bool
665 cs_post_writer_exists(int writer_id);
666 
667 /*----------------------------------------------------------------------------
668  * Return a pointer to the FVM writer associated to a writer_id.
669  *
670  * parameters:
671  * writer_id <-- associated writer id
672  *
673  * Returns:
674  * a pointer to a fvm_writer_t structure
675  *----------------------------------------------------------------------------*/
676 
677 fvm_writer_t *
678 cs_post_get_writer(int writer_id);
679 
680 /*----------------------------------------------------------------------------
681  * Add an activation time step for a specific writer or for all writers.
682  *
683  * If a negative value is provided, a previously added activation time
684  * step matching that absolute value will be removed, if present.
685  *
686  * parameters:
687  * writer_id <-- writer id, or 0 for all writers
688  * nt <-- time step value to add (or remove)
689  *----------------------------------------------------------------------------*/
690 
691 void
692 cs_post_add_writer_t_step(int writer_id,
693  int nt);
694 
695 /*----------------------------------------------------------------------------
696  * Add an activation time value for a specific writer or for all writers.
697  *
698  * If a negative value is provided, a previously added activation time
699  * step matching that absolute value will be removed, if present.
700  *
701  * parameters:
702  * writer_id <-- writer id, or 0 for all writers
703  * t <-- time value to add (or remove)
704  *----------------------------------------------------------------------------*/
705 
706 void
707 cs_post_add_writer_t_value(int writer_id,
708  double t);
709 
710 /*----------------------------------------------------------------------------
711  * Check for the existence of a post-processing mesh of the given id.
712  *
713  * parameters:
714  * mesh_id <-- mesh id to check
715  *
716  * returns:
717  * true if mesh with this id exists, false otherwise
718  *----------------------------------------------------------------------------*/
719 
720 bool
721 cs_post_mesh_exists(int mesh_id);
722 
723 /*----------------------------------------------------------------------------
724  * Modify an existing post-processing mesh.
725  *
726  * The lists of cells or faces are redefined, for example to update an
727  * extracted mesh based in "interesting" zones.
728  *
729  * It is not necessary to use this function if a mesh is simply deformed.
730  *
731  * parameters:
732  * mesh_id <-- id of mesh to modify (< 0 reserved, > 0 for user)
733  * n_cells <-- number of associated cells
734  * n_i_faces <-- number of associated interior faces
735  * n_b_faces <-- number of associated boundary faces
736  * cell_list <-> list of associated cells
737  * i_face_list <-> list of associated interior faces
738  * b_face_list <-> list of associated boundary faces
739  *
740  *----------------------------------------------------------------------------*/
741 
742 void
743 cs_post_modify_mesh(int mesh_id,
744  cs_lnum_t n_cells,
745  cs_lnum_t n_i_faces,
746  cs_lnum_t n_b_faces,
747  cs_lnum_t cell_list[],
748  cs_lnum_t i_face_list[],
749  cs_lnum_t b_face_list[]);
750 
751 /*----------------------------------------------------------------------------
752  * Return the default writer format name
753  *
754  * Returns:
755  * name of the default writer format
756  *----------------------------------------------------------------------------*/
757 
758 const char *
760 
761 /*----------------------------------------------------------------------------
762  * Return the default writer format options
763  *
764  * Returns:
765  * default writer format options string
766  *----------------------------------------------------------------------------*/
767 
768 const char *
770 
771 /*----------------------------------------------------------------------------
772  * Return the next "reservable" (i.e. non-user) writer id available.
773  *
774  * Returns:
775  * the smallest negative integer present, -1
776  *----------------------------------------------------------------------------*/
777 
778 int
780 
781 /*----------------------------------------------------------------------------
782  * Return the next "reservable" (i.e. non-user) mesh id available.
783  *
784  * Returns:
785  * the smallest negative integer present, -1
786  *----------------------------------------------------------------------------*/
787 
788 int
790 
791 /*----------------------------------------------------------------------------
792  * Update "active" or "inactive" flag of writers based on the time step.
793  *
794  * Writers are activated if their output frequency is a divisor of the
795  * current time step, or if their optional time step and value output lists
796  * contain matches for the current time step.
797  *
798  * parameters:
799  * ts <-- time step status structure
800  *----------------------------------------------------------------------------*/
801 
802 void
804 
805 /*----------------------------------------------------------------------------
806  * Force the "active" or "inactive" flag for a specific writer or for all
807  * writers for the current time step.
808  *
809  * parameters:
810  * writer_id <-- writer id, or 0 for all writers
811  * activate <-- false to deactivate, true to activate
812  *----------------------------------------------------------------------------*/
813 
814 void
815 cs_post_activate_writer(int writer_id,
816  bool activate);
817 
818 /*----------------------------------------------------------------------------
819  * Output post-processing meshes using associated writers.
820  *
821  * parameters:
822  * ts <-- time step status structure
823  *----------------------------------------------------------------------------*/
824 
825 void
827 
828 /*----------------------------------------------------------------------------
829  * Output a variable defined at cells or faces of a post-processing mesh
830  * using associated writers.
831  *
832  * parameters:
833  * mesh_id <-- id of associated mesh
834  * var_name <-- name of variable to output
835  * var_dim <-- 1 for scalar, 3 for vector
836  * interlace <-- if a vector, true for interlaced values, false otherwise
837  * use_parent <-- true if values are defined on "parent" mesh,
838  * false if values are defined on post-processing mesh
839  * var_type <-- variable's data type
840  * cel_vals <-- cell values
841  * i_face_vals <-- interior face values
842  * b_face_vals <-- boundary face values
843  * ts <-- time step status structure, or NULL
844  *----------------------------------------------------------------------------*/
845 
846 void
847 cs_post_write_var(int mesh_id,
848  const char *var_name,
849  int var_dim,
850  bool interlace,
851  bool use_parent,
852  cs_post_type_t var_type,
853  const void *cel_vals,
854  const void *i_face_vals,
855  const void *b_face_vals,
856  const cs_time_step_t *ts);
857 
858 /*----------------------------------------------------------------------------
859  * Output a variable defined at vertices of a post-processing mesh using
860  * associated writers.
861  *
862  * parameters:
863  * mesh_id <-- id of associated mesh
864  * var_name <-- name of variable to output
865  * var_dim <-- 1 for scalar, 3 for vector
866  * interlace <-- if a vector, true for interlaced values, false otherwise
867  * use_parent <-- true if values are defined on "parent" mesh,
868  * false if values are defined on post-processing mesh
869  * var_type <-- variable's data type
870  * vtx_vals <-- vertex values
871  * ts <-- time step status structure, or NULL
872  *----------------------------------------------------------------------------*/
873 
874 void
875 cs_post_write_vertex_var(int mesh_id,
876  const char *var_name,
877  int var_dim,
878  bool interlace,
879  bool use_parent,
880  cs_post_type_t var_type,
881  const void *vtx_vals,
882  const cs_time_step_t *ts);
883 
884 /*----------------------------------------------------------------------------
885  * Output an existing lagrangian particle attribute at particle
886  * positions or trajectory endpoints of a particle mesh using
887  * associated writers.
888  *
889  * parameters:
890  * mesh_id <-- id of associated mesh
891  * attr <-- associated particle attribute id
892  * var_name <-- name of variable to output
893  * component_id <-- if -1 : extract the whole attribute
894  * if >0 : id of the component to extract
895  * ts <-- time step status structure, or NULL
896  *----------------------------------------------------------------------------*/
897 
898 void
900  int attr_id,
901  const char *var_name,
902  int component_id,
903  const cs_time_step_t *ts);
904 
905 /*----------------------------------------------------------------------------
906  * Update references to parent mesh of post-processing meshes in case of
907  * computational mesh cell renumbering.
908  *
909  * This function may be called only once, after possible renumbering of cells,
910  * to update existing post-processing meshes. Post-processing meshes defined
911  * after renumbering will automatically be based upon the new numbering,
912  * so this function will not need to be called again.
913  *
914  * parameters:
915  * init_cell_num <-- initial cell numbering (1 to n, new -> old)
916  *----------------------------------------------------------------------------*/
917 
918 void
919 cs_post_renum_cells(const cs_lnum_t init_cell_num[]);
920 
921 /*----------------------------------------------------------------------------
922  * Update references to parent mesh of post-processing meshes in case of
923  * computational mesh interior and/or boundary faces renumbering.
924  *
925  * This function may be called only once, after possible renumbering of faces,
926  * to update existing post-processing meshes. Post-processing meshes defined
927  * after renumbering will automatically be based upon the new numbering,
928  * so this function will not need to be called again.
929  *
930  * parameters:
931  * init_i_face_num <-- initial interior numbering (1 to n, new -> old)
932  * init_b_face_num <-- initial boundary numbering (1 to n, new -> old)
933  *----------------------------------------------------------------------------*/
934 
935 void
936 cs_post_renum_faces(const cs_lnum_t init_i_face_num[],
937  const cs_lnum_t init_b_face_num[]);
938 
939 /*----------------------------------------------------------------------------
940  * Initialize post-processing writers
941  *----------------------------------------------------------------------------*/
942 
943 void
945 
946 /*----------------------------------------------------------------------------
947  * Initialize main post-processing meshes
948  *
949  * The check_flag variable is a mask, used for additionnal post-processing:
950  *
951  * - If (check_flag & 1), volume submeshes are output by groups if more
952  * than one group is present and the default writer uses the EnSight format.
953  *
954  * - If (check_flag & 2), boundary submeshes are output by groups if more
955  * than one group is present and the default writer uses the EnSight format.
956  *
957  * Note that all alias-type post-processing meshes and the meshes they
958  * relate to should have been defined before calling this function, so it is
959  * recommended that user-defined post-processing meshes be defined before
960  * calling this function, though specific "automatic" meshes (for example
961  * those related to couplings) may be defined between this call and a
962  * time loop.
963  *
964  * parameters:
965  * check_flag <-- mask used for additional output
966  *----------------------------------------------------------------------------*/
967 
968 void
969 cs_post_init_meshes(int check_mask);
970 
971 /*----------------------------------------------------------------------------
972  * Loop on post-processing meshes to output variables.
973  *
974  * This handles all default fields output, as well as all
975  * registred output functions.
976  *
977  * parameters:
978  * ts <-- time step status structure, or NULL
979  *----------------------------------------------------------------------------*/
980 
981 void
983 
984 /*----------------------------------------------------------------------------
985  * Destroy all structures associated with post-processing
986  *----------------------------------------------------------------------------*/
987 
988 void
989 cs_post_finalize(void);
990 
991 /*----------------------------------------------------------------------------
992  * Postprocess free (isolated) faces of the current global mesh
993  *----------------------------------------------------------------------------*/
994 
995 void
997 
998 /*----------------------------------------------------------------------------
999  * Initialize post-processing writer with same format and associated
1000  * options as default writer, but no time dependency, intended to
1001  * troubleshoot errors.
1002  *----------------------------------------------------------------------------*/
1003 
1004 void
1006 
1007 /*----------------------------------------------------------------------------
1008  * Initialize post-processing writer with same format and associated
1009  * options as default writer, but no time dependency, and associate
1010  * and output global volume mesh.
1011  *
1012  * This is intended to help troubleshoot errors using fields based
1013  * on cells.
1014  *
1015  * returns:
1016  * id of error output mesh (< 0), or 0 if all writers are deactivated
1017  *----------------------------------------------------------------------------*/
1018 
1019 int
1021 
1022 /*----------------------------------------------------------------------------
1023  * Register a processing of time-dependent variables to the call to
1024  * cs_post_write_vars().
1025  *
1026  * Note: if the input pointer is non-NULL, it must point to valid data
1027  * when the output function is called, so either:
1028  * - that value or structure should not be temporary (i.e. local);
1029  * - post-processing output must be ensured using cs_post_write_var()
1030  * or similar before the data pointed to goes out of scope.
1031  *
1032  * parameters:
1033  * function <-- function to register
1034  * input <-> pointer to optional (untyped) value or structure.
1035  *----------------------------------------------------------------------------*/
1036 
1037 void
1039  void *input);
1040 
1041 /*----------------------------------------------------------------------------
1042  * Register a processing of time-dependent variables than can be output
1043  * on different meshes to the call to cs_post_write_vars().
1044  *
1045  * Note: if the input pointer is non-NULL, it must point to valid data
1046  * when the output function is called, so either:
1047  * - that value or structure should not be temporary (i.e. local);
1048  * - post-processing output must be ensured using cs_post_write_var()
1049  * or similar before the data pointed to goes out of scope.
1050  *
1051  * parameters:
1052  * function <-- function to register
1053  * input <-> pointer to optional (untyped) value or structure.
1054  *----------------------------------------------------------------------------*/
1055 
1056 void
1058  void *input);
1059 
1060 /*----------------------------------------------------------------------------*/
1061 
1063 
1064 #endif /* __CS_POST_H__ */
void cs_post_write_vars(const cs_time_step_t *ts)
Loop on post-processing meshes to output variables.
Definition: cs_post.c:5105
Definition: cs_post.h:73
const char * cs_post_get_default_format(void)
Return the default writer format name.
Definition: cs_post.c:3905
time step descriptor
Definition: cs_time_step.h:51
void cs_post_mesh_get_i_face_ids(int mesh_id, cs_lnum_t i_face_ids[])
Get a postprocessing mesh's list of boundary faces.
Definition: cs_post.c:3666
void cs_post_init_error_writer(void)
Initialize post-processing writer with same format and associated options as default writer...
Definition: cs_post.c:5700
cs_post_type_t
Postprocessing input variable type.
Definition: cs_post.h:68
void cs_post_write_var(int mesh_id, const char *var_name, int var_dim, bool interlace, bool use_parent, cs_post_type_t var_type, const void *cel_vals, const void *i_face_vals, const void *b_face_vals, const cs_time_step_t *ts)
Output a variable defined at cells or faces of a post-processing mesh using associated writers...
Definition: cs_post.c:4198
Definition: cs_post.h:72
void cs_post_define_surface_mesh_by_func(int mesh_id, const char *mesh_name, cs_post_elt_select_t *i_face_select_func, cs_post_elt_select_t *b_face_select_func, void *i_face_select_input, void *b_face_select_input, bool time_varying, bool add_groups, bool auto_variables, int n_writers, const int writer_ids[])
Define a surface post-processing mesh using selection functions.
Definition: cs_post.c:3130
void cs_post_write_vertex_var(int mesh_id, const char *var_name, int var_dim, bool interlace, bool use_parent, cs_post_type_t var_type, const void *vtx_vals, const cs_time_step_t *ts)
Output a variable defined at vertices of a post-processing mesh using associated writers.
Definition: cs_post.c:4438
void cs_post_free_mesh(int mesh_id)
Remove a post-processing mesh.
Definition: cs_post.c:3785
void cs_post_init_writers(void)
Initialize post-processing writers.
Definition: cs_post.c:4905
void( cs_post_time_dep_output_t)(void *input, const cs_time_step_t *ts)
Definition: cs_post.h:123
void cs_post_activate_by_time_step(const cs_time_step_t *ts)
Update "active" or "inactive" flag of writers based on the time step.
Definition: cs_post.c:3965
#define BEGIN_C_DECLS
Definition: cs_defs.h:405
const int * cs_post_mesh_get_ent_flag(int mesh_id)
Get a postprocessing meshes entity presence flag.
Definition: cs_post.c:3559
void cs_post_define_particles_mesh_by_func(int mesh_id, const char *mesh_name, cs_post_elt_select_t *p_select_func, void *p_select_input, bool trajectory, bool auto_variables, int n_writers, const int writer_ids[])
Define a particles post-processing mesh using a selection function.
Definition: cs_post.c:3260
int cs_post_get_free_writer_id(void)
Return the next "reservable" (i.e. non-user) writer id available.
Definition: cs_post.c:3933
int cs_post_init_error_writer_cells(void)
Initialize post-processing writer with same format and associated options as default writer...
Definition: cs_post.c:5736
void cs_post_define_existing_mesh(int mesh_id, fvm_nodal_t *exp_mesh, int dim_shift, bool transfer, bool auto_variables, int n_writers, const int writer_ids[])
Create a post-processing mesh associated with an existing exportable mesh representation.
Definition: cs_post.c:3395
fvm_writer_time_dep_t
Definition: fvm_writer.h:57
fvm_writer_t * cs_post_get_writer(int writer_id)
Return a pointer to the FVM writer associated to a writer_id.
Definition: cs_post.c:4070
Definition: cs_post.h:69
void cs_post_renum_faces(const cs_lnum_t init_i_face_num[], const cs_lnum_t init_b_face_num[])
Update references to parent mesh of post-processing meshes in case of computational mesh interior and...
Definition: cs_post.c:4784
void cs_post_init_meshes(int check_mask)
Initialize main post-processing meshes.
Definition: cs_post.c:4979
void cs_post_mesh_get_b_face_ids(int mesh_id, cs_lnum_t b_face_ids[])
Get a postprocessing mesh's list of boundary faces.
Definition: cs_post.c:3739
cs_lnum_t cs_post_mesh_get_n_b_faces(int mesh_id)
Get a postprocessing mesh's number of boundary faces.
Definition: cs_post.c:3709
cs_lnum_t cs_post_mesh_get_n_i_faces(int mesh_id)
Get a postprocessing mesh's number of interior faces.
Definition: cs_post.c:3636
const char * cs_post_get_default_format_options(void)
Return the default writer format options.
Definition: cs_post.c:3919
void cs_post_define_particles_mesh(int mesh_id, const char *mesh_name, const char *cell_criteria, double density, bool trajectory, bool auto_variables, int n_writers, const int writer_ids[])
Define a particles post-processing mesh.
Definition: cs_post.c:3192
void cs_post_add_time_mesh_dep_output(cs_post_time_mesh_dep_output_t *function, void *input)
Register a processing of time-dependent variables than can be output on different meshes to the call ...
Definition: cs_post.c:5838
void cs_post_write_meshes(const cs_time_step_t *ts)
Output post-processing meshes using associated writers.
Definition: cs_post.c:4152
void cs_post_define_volume_mesh(int mesh_id, const char *mesh_name, const char *cell_criteria, bool add_groups, bool auto_variables, int n_writers, const int writer_ids[])
Define a volume post-processing mesh.
Definition: cs_post.c:2956
Definition: cs_post.h:71
void cs_post_finalize(void)
Destroy all structures associated with post-processing.
Definition: cs_post.c:5384
void cs_post_define_writer(int writer_id, const char *case_name, const char *dir_name, const char *fmt_name, const char *fmt_opts, fvm_writer_time_dep_t time_dep, bool output_at_end, int frequency_n, double frequency_t)
Define a writer; this objects manages a case's name, directory, and format, as well as associated mes...
Definition: cs_post.c:2831
void cs_post_define_surface_mesh(int mesh_id, const char *mesh_name, const char *i_face_criteria, const char *b_face_criteria, bool add_groups, bool auto_variables, int n_writers, const int writer_ids[])
Define a surface post-processing mesh.
Definition: cs_post.c:3061
void cs_post_set_changing_connectivity(void)
Configure the post-processing output so that mesh connectivity may be automatically updated...
Definition: cs_post.c:4893
void cs_post_modify_mesh(int mesh_id, cs_lnum_t n_cells, cs_lnum_t n_i_faces, cs_lnum_t n_b_faces, cs_lnum_t cell_list[], cs_lnum_t i_face_list[], cs_lnum_t b_face_list[])
void( cs_post_elt_select_t)(void *input, cs_lnum_t *n_elts, cs_lnum_t **elt_list)
Function pointer to elements selection definition.
Definition: cs_post.h:100
int cs_post_get_free_mesh_id(void)
Return the next "reservable" (i.e. non-user) mesh id available.
Definition: cs_post.c:3947
void cs_post_set_deformable(void)
Configure the post-processing output so that a mesh displacement field may be output automatically fo...
Definition: cs_post.c:4874
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:292
cs_lnum_t cs_post_mesh_get_n_cells(int mesh_id)
Get a postprocessing mesh's number of cells.
Definition: cs_post.c:3577
void cs_post_mesh_get_cell_ids(int mesh_id, cs_lnum_t *cell_ids)
Get a postprocessing mesh's list of cells.
Definition: cs_post.c:3607
void cs_post_activate_writer(int writer_id, bool activate)
Force the "active" or "inactive" flag for a specific writer or for all writers for the current time s...
Definition: cs_post.c:4040
void cs_post_add_free_faces(void)
Postprocess free (isolated) faces of the current global mesh.
Definition: cs_post.c:5489
#define END_C_DECLS
Definition: cs_defs.h:406
void cs_post_add_writer_t_value(int writer_id, double t)
Add an activation time value for a specific writer or for all writers.
Definition: cs_post.c:4125
void cs_post_add_time_dep_output(cs_post_time_dep_output_t *function, void *input)
Register a processing of time-dependent variables to the call to cs_post_write_vars().
Definition: cs_post.c:5797
Definition: cs_post.h:70
void cs_post_define_edges_mesh(int mesh_id, int base_mesh_id, int n_writers, const int writer_ids[])
Create a mesh based upon the extraction of edges from an existing mesh.
Definition: cs_post.c:3519
void( cs_post_time_mesh_dep_output_t)(void *input, int mesh_id, int cat_id, int ent_flag[4], cs_lnum_t n_cells, cs_lnum_t n_i_faces, cs_lnum_t n_b_faces, const cs_lnum_t cell_list[], const cs_lnum_t i_face_list[], const cs_lnum_t b_face_list[], const cs_time_step_t *ts)
Definition: cs_post.h:157
void cs_post_write_particle_values(int mesh_id, int attr_id, const char *var_name, int component_id, const cs_time_step_t *ts)
Output an existing lagrangian particle attribute at particle positions or trajectory endpoints of a p...
Definition: cs_post.c:4552
void cs_post_define_alias_mesh(int mesh_id, int aliased_mesh_id, bool auto_variables, int n_writers, const int writer_ids[])
Create an alias to a post-processing mesh.
Definition: cs_post.c:3323
bool cs_post_mesh_exists(int mesh_id)
Check for the existence of a post-processing mesh of the given id.
Definition: cs_post.c:3880
void cs_post_add_writer_t_step(int writer_id, int nt)
Add an activation time step for a specific writer or for all writers.
Definition: cs_post.c:4097
bool cs_post_writer_exists(int writer_id)
Check for the existence of a writer of the given id.
Definition: cs_post.c:3851
void cs_post_define_volume_mesh_by_func(int mesh_id, const char *mesh_name, cs_post_elt_select_t *cell_select_func, void *cell_select_input, bool time_varying, bool add_groups, bool auto_variables, int n_writers, const int writer_ids[])
Define a volume post-processing mesh using a selection function.
Definition: cs_post.c:3015
void cs_post_renum_cells(const cs_lnum_t init_cell_num[])
Update references to parent mesh of post-processing meshes in case of computational mesh cell renumbe...
Definition: cs_post.c:4708