7.0
general documentation
Probes and profiles

About Probes and profiles

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 profile, 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 those in multiple stages, using first cs_probe_set_create then a series of calls to cs_probe_set_add_probe.

The following example shows how probes may be added using that function.

{
cs_probe_set_t *pset = cs_probe_set_create("Monitoring");
cs_probe_set_add_probe(pset, 0.25, 0.025, 0.025, "M1");
cs_probe_set_add_probe(pset, 0.50, 0.025, 0.025, "M2");
cs_probe_set_add_probe(pset, 0.75, 0.025, 0.025, "M3");
}
cs_probe_set_t * cs_probe_set_create(const char *name)
Create a new set of probes.
Definition: cs_probe.c:870
void cs_probe_set_add_probe(cs_probe_set_t *pset, cs_real_t x, cs_real_t y, cs_real_t z, const char *label)
Add a new probe to an existing set of probes.
Definition: cs_probe.c:894
struct _cs_probe_set_t cs_probe_set_t
Definition: cs_probe.h:53

The same set could also be defined using predifined arrays:

{
const cs_real_t coords[][3] = {{0.25, 0.025, 0.025},
{0.50, 0.025, 0.025},
{0.75, 0.025, 0.025}};
const char *labels[] = {"M1", "M2", "M3"};
3,
coords,
labels);
}
double cs_real_t
Floating-point value.
Definition: cs_defs.h:304
cs_probe_set_t * cs_probe_set_create_from_array(const char *name, int n_probes, const cs_real_3_t *coords, const char **labels)
Define a new set of probes from an array of coordinates.
Definition: cs_probe.c:942

In both cases, labels are optional (NULL may be used instead).

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.

A writer (id = CS_POST_WRITER_PROBES) using the format "time_plot" is associated by default to a set of monitoring probes. This is not the case for profiles.

Profiles are special probe sets, for which a curvilinear coordinate is usually provided (or deduced, when cs_probe_set_create_from_segment or cs_probe_set_create_from_local construction function is used). Curvilinear coordinates may also be assigned to probe sets generated using cs_probe_set_create or cs_probe_set_create_from_array by using the cs_probe_set_assign_curvilinear_abscissa function.

Instead of being assigned by default to a time plot, profiles are generally used with writers using the "plot" format (with a "dat" or "csv" sub-option). Instead of using one file per variable with one column per point and one line per output time, this produces one file pour output time, with une column per variable and one line per point. But they may also be used with time plots (as a regular probe set), or as with any post-processing output mesh, with 3D formats such as EnSight or MED.

The following example shows how to simply define a profile on a given segment, and associate it to writer 2:

{
cs_coord_3_t start = {0., 0.025, 0.025};
cs_coord_3_t end = {1., 0.025, 0.025};
int writer_ids[] = {2};
11, // n_probes
start, // start coordinates
end); // end coordinates
cs_probe_set_associate_writers(pset, 1, writer_ids);
}
cs_coord_t cs_coord_3_t[3]
Definition: cs_defs.h:313
cs_probe_set_t * cs_probe_set_create_from_segment(const char *name, int n_probes, const cs_real_t start_coords[3], const cs_real_t end_coords[3])
Define a new set of probes from the segment spanned by two points.
Definition: cs_probe.c:982
void cs_probe_set_associate_writers(cs_probe_set_t *pset, int n_writers, const int *writer_ids)
Associate a list of writers to a probe set.
Definition: cs_probe.c:1147

Probe sets (including profiles) may also be located along the domain boundary, if this is specified. In the following example, we set the "boundary" option to "true" to specify that the probes should be located on the boundary instead of the default volume mesh. We could also set a "criteria" option to define a selection filter for the portion of the mesh in which probes should be located (by default, the whole mesh).

Here We also choose to "snap" the points to the nearest vertices. Snapping probes to cell centers or vertices is useful mainly when the values to plot are located on those points.

{
cs_coord_3_t start = {0., 0., 0.};
cs_coord_3_t end = {1., 0., 0.};
11, // n_probes
start, // start coordinates
end); // end coordinates
int writer_ids[] = {2};
cs_probe_set_associate_writers(pset, 1, writer_ids);
cs_probe_set_option(pset, "boundary", "true");
}
void cs_probe_set_option(cs_probe_set_t *pset, const char *keyname, const char *keyval)
Set optional parameters related to the management of a set of probes.
Definition: cs_probe.c:1327
void cs_probe_set_snap_mode(cs_probe_set_t *pset, cs_probe_snap_t snap_mode)
Set snap mode related to the management of a set of probes.
Definition: cs_probe.c:1291
@ CS_PROBE_SNAP_VERTEX
Definition: cs_probe.h:59

Defining output on a probe set

To select a specific set of fields to output with a given probe set or profile, the cs_probe_set_associate_field function may be used. It allows specifying whether the output relates to all associated writers or specific ones, and for multidimensional fields, allows selecting specific components (comp_id = -1 for all components, or the (0 to n-1)-th component if filtering is desired.

This is used in general for probe sets whose "automatic" variables output is turned off (using cs_probe_set_auto_var), though it can be used to extend that glob setting.

Finally, the user may choose to output the curvilinear coordinates associated with a profile and/or the point coordinates, using the cs_probe_set_auto_curvilinear_coords and cs_probe_set_auto_cartesian_coords respectively, since these are not output by default.

This last example illustrates a combination of those possibilities:

{
cs_coord_3_t start = {0., 0., 0.};
cs_coord_3_t end = {1., 0., 0.};
11, // n_probes
start, // start coordinates
end); // end coordinates
int writer_ids[] = {2};
cs_probe_set_associate_writers(pset, 1, writer_ids);
cs_probe_set_option(pset, "boundary", "true");
}

Advanced profile definitions

As with regular meshes, profiles may be defined using user functions.

Definition of a series of profiles

In this example, we define a series of profiles. To avoid redundant code, an array defining both the name of each profile and the matching x coordinate (as a text string) is defined. The code then loops along these array values to define the series:

static const char *line_defs[]
= {"-5.87", "buicesat-6",
"2.59", "buicesat03",
"5.98", "buicesat06",
"12.75", "buicesat13",
"13.56", "buicesat14",
"16.14", "buicesat16",
"16.93", "buicesat17",
"19.53", "buicesat19",
"20.32", "buicesat20",
"22.91", "buicesat23",
"23.71", "buicesat24",
"26.3", "buicesat26",
"27.09", "buicesat27",
"29.69", "buicesat29",
"30.48", "buicesat30",
"33.07", "buicesat33",
"33.87", "buicesat34",
"39.85", "buicesat40",
"46.62", "buicesat47",
"53.39", "buicesat53",
"60.17", "buicesat60",
"66.94", "buicesat67",
"73.71", "buicesat74"};
for (int i = 0; i < 23; i++) {
/* Define profiles */
= cs_probe_set_create_from_local(line_defs[i*2+1],
_cell_x_profile_probes_define,
(void *)line_defs[i*2]); /* input */
/* Associate writers */
const int writer_ids[] = {CS_POST_WRITER_PROFILES};
cs_probe_set_associate_writers(pset, 1, writer_ids);
}
#define CS_POST_WRITER_PROFILES
Definition: cs_post.h:70
cs_probe_set_t * cs_probe_set_create_from_local(const char *name, cs_probe_set_define_local_t *p_define_func, void *p_define_input)
Define a new set of probes from rank-local definition function.
Definition: cs_probe.c:1050

As we observe here, the cs_probe_set_create_from_local requires a process-local definition, calling a user-defined function. This requires that the line_defs array be defined as static, so as to be available when this function is called. For this example, the function is defined as follows (before the calling function, preferably in the file's local function definitions section).

static void
_cell_x_profile_probes_define(void *input,
cs_lnum_t *n_elts,
cs_real_3_t **coords,
cs_real_t **s)
{
/* Determine x value from input string, to define
associated segment (with fixed y and z values) */
const char *x_str = (const char *)input;
cs_real_t x = atof(x_str);
cs_real_t seg[6] = {x, 0.1, -0.05, x, -5, -0.05};
/* Call general cell selection function with adapted input */
cs_cell_segment_intersect_probes_define(seg, n_elts, coords, s);
}
cs_real_t cs_real_3_t[3]
vector of 3 floating-point values
Definition: cs_defs.h:317
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:298
void cs_cell_segment_intersect_probes_define(void *input, cs_lnum_t *n_elts, cs_real_3_t **coords, cs_real_t **s)
Define probes based on the centers of cells intersected by a given segment.
Definition: cs_post_util.c:635

Boundary profiles

Probes and profiles may also be associated to the mesh boundary.

In the following example, a profile is defined based on a mesh boundary selection criterion, using the predefined cs_b_face_criterion_probes_define (which assumes curvilinear coordinates based on the "x" direction):

= cs_probe_set_create_from_local("foil_profile", /* probes set name */
/* probe def. function */
(void *)"FOIL_WALL"); /* input */
/* Indicate that the probes are located on the boundary */
cs_probe_set_option(pset, "boundary", "true");
/* Associate profile writer to this probes set */
const int writer_ids[] = {CS_POST_WRITER_PROFILES};
cs_probe_set_associate_writers(pset, 1, writer_ids);
void cs_b_face_criterion_probes_define(void *input, cs_lnum_t *n_elts, cs_real_3_t **coords, cs_real_t **s)
Define a profile based on centers of faces defined by a given criterion.
Definition: cs_post_util.c:696

and in the below example using an array of 2 selection criteria:

static const char *wall_defs[]
= {"UP", "buicstr",
"DOWN", "buicinc"};
for (int i = 0; i < 2; i++) {
= cs_probe_set_create_from_local(wall_defs[i*2+1],
(void *)wall_defs[i*2]); /* input */
cs_probe_set_option(pset, "boundary", "true");
/* Associate writers */
const int writer_ids[] = {CS_POST_WRITER_PROFILES};
cs_probe_set_associate_writers(pset, 1, writer_ids);
}