![]() |
programmer's documentation
|
C user functions for definition of postprocessing output. These subroutines are called in all cases.
If the Code_Saturne GUI is used, this file is not required (but may be used to override parameters entered through the GUI, and to set parameters not accessible through the GUI).
Several functions are present in the file, each destined to defined specific parameters.
The functions defined in cs_user_postprocess.c, namely cs_user_postprocess_writers, cs_user_postprocess_meshes, cs_user_postprocess_probes and cs_user_postprocess_activate allow for the definition of post-processing output formats and frequency, and for the definition of surface or volume sections, in order to generate chronological outputs in EnSight, MED, or CGNS format, as in-situ visualization using Catalyst.
Point sets (probes and profiles) may also be defined, with outputs in the more classical comma-separated (csv) or white-space-separated (dat) text files, in addition to the aforementioned output types.
The main concepts are those of writers and meshes, which must be associated to produce outputs.
A writer combines the definition of an output type, frequency, path, and name. One or more writers can be defined using the GUI and the cs_user_postprocess_writers user function.
A mesh is based on a subset of the the computational mesh, or point sets such as particles or probe sets. One or more meshes can be defined using the GUI and the cs_user_postprocess_meshes user function.
In order to allow the user to add an output format to the main output format, or to add a mesh to the default output, the lists of standard and user meshes and writers are not separated. Negative numbers are reserved for the non-user items. For instance, the mesh numbers -1 and -2 correspond respectively to the global mesh and to boundary faces, generated by default, and the writer -1 corresponds to the default post-processing writer.
The user chooses the numbers corresponding to the post-processing meshes and writers he wants to create. These numbers must be positive integers. It is possible to associate a user mesh with the standard post-processing case (-1), or to ask for outputs regarding the boundary faces (-2) associated with a user writer.
For safety, the output frequency and the possibility to modify the post-processing meshes are associated with the writers rather than with the meshes. This logic avoids unwanted generation of inconsistent post-processing outputs. For instance, EnSight would not be able to read a case in which one field is output to a given part every 10 time steps, while another field is output to the same part every 200 time steps.
Writers may be defined in the cs_user_postprocess_writers function.
Flushing parameters for time plots may also be defined here. By default, for best performance, time plot files are kept open, and flushing is not forced. This behavior may be modified, as in the following example. The default settings should be changed before time plots are defined.
The following local variable definitions can shared beween several examples:
In the following example, the default writer is redefined, so as to modify some parameters which have been set by default or by the GUI:
Polygons and polyhedra may also be divided into simpler elements, as in the example below (only for polyhedra here), using MED format output:
In the next example, the defined writer discards polyhedra, and allows for transient mesh connectivity (i.e. meshes changing with time); text output is also forced:
In this last example, a plot writers is defined. Such a writer will be used to output probe, profile, or other point data (probes may be output to 3D formats, but plot and time plot outputs drop cell or face-based ouptut).
Postprocessing meshes may be defined in the cs_user_postprocess_meshes function, using one of several postprocessing mesh creation functions (cs_post_define_volume_mesh, cs_post_define_volume_mesh_by_func, cs_post_define_surface_mesh, cs_post_define_surface_mesh_by_func, cs_post_define_particles_mesh, cs_post_define_particles_mesh_by_func, cs_post_define_probe_mesh, cs_post_define_alias_mesh, cs_post_define_existing_mesh, and cs_post_define_edges_mesh).
It is possible to output variables which are normally automatically output on the main volume or boundary meshes to a user mesh which is a subset of one of these by setting the auto_variables
argument of one of the cs_post_define_
..._mesh to true
.
It is not possible to mix cells and faces in the same mesh (most of the post-processing tools being perturbed by such a case). More precisely, faces adjacent to selected cells and belonging to face or cell groups may be selected when the add_groups
of cs_post_define_
..._mesh functions is set to true
, so as to maintain group information, but those faces will only be written for formats supporting this (such as MED), and will only bear groups, not variable fields.
The additional variables to post-process on the defined meshes will be specified in the subroutine usvpst in the cs_user_postprocess_var.f90 file.
In the example below, the default boundary mesh output is suppressed by redefining it, with no writer association:
Note that the default behavior for meshes -1 and -2 is:
In the following example, we use a geometric criteria to output only a subset of the main mesh, and associate the resulting mesh with user-defined writers 1 and 4:
The same variables will be output through all writers associated to a mesh. In cases where different variables of a same mesh should be output through different writers, the solution is to define one or several "aliases" of that mesh. An alias shares all the attributes of its parent mesh (without duplication), except its number. allowing to assign a different id, writers, and variables to each secondary copy of the mesh, without the overhead of a full copy. The cs_post_define_alias_mesh function may be used for such a purpose. Its use is illustrated in the following example:
Modification of a post-processing mesh or its alias over time is always limited by the most restrictive "writer" to which its meshes have been associated (parts of the structures being shared in memory). It is possible to define as many aliases as are required for a true mesh, but an alias cannot be defined for another alias.
More advanced mesh element selection is possible using cs_post_define_volume_mesh_by_func or cs_post_define_surface_mesh_by_func, which allow defining volume or surface meshes using user-defined element lists.
The possibility to modify a mesh over time is limited by the most restrictive writer which is associated with. For instance, if writer 1 allows the modification of the mesh topology (argument time_dep
= FVM_WRITER_TRANSIENT_CONNECT in the call to cs_post_define_writer) and writer 2 allows no modification (time_dep
= FVM_WRITER_FIXED_MESH), a user post-processing mesh associated with writers 1 and 2 will not be modifiable, but a mesh associated with writer 1 only will be modifiable. The modification can be done by using the advanced cs_post_define_volume_mesh_by_func or cs_post_define_surface_mesh_by_func, associated with a user-defined selection function based on time-varying criteria (such as field values being above a given threshold). If the time_dep
argument is set to true
, the mesh will be redefined using the selection function at each output time step for every modifiable mesh.
In the following example, we build a surface mesh containing interior faces separating cells of group "2" from those of group "3", (assuming no cell has both colors), as well as boundary faces of group "4".
This is done by first defining 2 selection functions, whose arguments and behavior match the cs_post_elt_select_t type.
The function for selection of interior faces separating cells of two groups also illustrates the usage of the cs_selector_get_family_list function to build a mask allowing direct checking of this criterion when comparing cells adjacent to a given face:
The function for selection of boundary faces is simpler, as it simply needs to apply the selection criterion for boundary faces:
Given these tow functions, the mesh can be defined using the cs_post_define_surface_mesh_by_func function, passing it the user-defined selection functions (actually, function pointers):
A mesh defined through the advanced cs_post_define_surface_mesh_by_func, cs_post_define_volume_mesh_by_func, or cs_post_define_particles_mesh_by_func may vary in time, as long as the matching time_varying
argument is set to true
, and the mesh (or aliases thereof) id only associated to writers defined with the FVM_WRITER_TRANSIENT_CONNECT option. In the case of particles, which always vary in time, this allows also varying the selection (filter) function with time.
In the following example, we build a volume mesh containing cells with values of field named "He_fraction" greater than 0.05.
First, we define the selection function:
Then, we simply define matching volume mesh passing the associated selection function pointer:
The matching function will be called at all time steps requiring output of this mesh.
In cases where a mesh containing polygonal elements is output through a writer configured to divide polygons into triangles (for example when visualization tools do not support polygons, or when highly non convex faces lead to visualization artifacts), it may be useful to extract a mesh containing the edges of the original mesh so as to view the polygon boundaries as an overlay.
In the following example, we build such a mesh (with id 5), based on the faces of a mesh with id 1:
By default, a post-processing frequency is defined for each writer, as defined using the GUI or through the cs_user_postprocess_writers function. For each writer, the user may define if an output is automatically generated at the end of the calculation, even if the last time step is not a multiple of the required time step number of physical time.
For finer control, the cs_user_postprocess_activate function file may be used to specify when post-processing outputs will be generated, overriding the default behavior.
In the following example, all output is deactivated until time step 1000 is reached, at which time the normal behavior resumes:
Sets of probes may also be defined through the cs_user_postprocess_probes function, to allow for extraction and output of values at specific mesh locations, often with a higher time frequency than for volume or surface meshes.
Probe sets, and profiles (which can be viewed as a series of probes lying on a user-defined curve) are handled as a point mesh, which can be associated with plot and time_plot 2D-plot writers, as well as any of the general (3D-output) writer types (the priviledged writer types being plot for a , and time_plot for other probes).
Probe sets may be defined using the cs_probe_set_create_from_array function. In some cases, it might be useful to define thos ses in multiple stages, using first cs_probe_set_create then a series of calls to cs_probe_set_add_probe.
Probe set creation functions return a pointer to a cs_probe_set_t structure which can be used to specify additional options using the cs_probe_set_option function.
For the mesh parts defined using the GUI or in cs_user_postprocess.c, the usvpst subroutine of cs_user_postprocess_var.f90 file may be used to specify the variables to post-process (called for each "part", at every active time step of an associated writer, see cs_user_postprocess.c.
The output of a given variable is generated by means of a call to the subroutine post_write_var}.