7.4 Sampling data

OpenFOAM provides a set of sampling function objects to sample field data, either through a 1D line for plotting on graphs or a 2D plane and 3D surfaces for displaying as images. Each sampling tool is specified in a dictionary either in the main functions dictionary of the controlDict file, or separate files in the case system directory. The data can be written in a range of formats including well-known graphing packages such as Grace/xmgr, gnuplot and jPlot.

The plateHole tutorial case in the $FOAM_TUTORIALS/stressAnalysis/solidDisplacementFoam directory also contains an example for 1D line sampling:

17    setConfig
18    {
19        axis    y;
20    }
21
22    // Must be last entry
23    #includeEtc "caseDicts/postProcessing/graphs/graph.cfg"
24}
25
26// ************************************************************************* //


Keyword

Options Description



interpolationScheme

cell
cellPoint
cellPointFace
pointMVC
cellPatchConstrained
Cell-centre value assumed constant over cell
Linear weighted interpolation using cell values
Mixed linear weighted / cell-face interpolation
Point values only (Mean Value Coordinates)
As cell but uses face value on boundary faces

setFormat

raw
gnuplot
xmgr
jplot
vtk
ensight
csv
Raw ASCII data in columns
Data in gnuplot format
Data in Grace/xmgr format
Data in jPlot format
Data in VTK format
Data in EnSight format
Data in CSV format

surfaceFormat

null
foamFile
dx
vtk
raw
stl
ensight
boundaryData
starcd
nastran
Suppresses output
points, faces, values file
DX scalar or vector format
VTK ASCII format
      xyz  \relax \special {t4ht= values for use with e.g.gnuplotsplot
ASCII STL; just surface, no values
EnSight surface format
A form that can be used with timeVaryingMapped boundary conditions
Nastran surface format

fields

List of fields to be sampled, e.g. for velocity U:

U Writes all components of                             U  \relax \special {t4ht=

sets

List of 1D sets subdictionaries — see Table 7.4

surfaces

List of 2D surfaces subdictionaries — see Table 7.5 and Table 7.6




Table 7.3: keyword entries for sampleDict.

The dictionary contains the following entries:

interpolationScheme
the scheme of data interpolation;
sets
the locations within the domain that the fields are line-sampled (1D).
surfaces
the locations within the domain that the fields are surface-sampled (2D).
setFormat
the format of line data output;
surfaceFormat
the format of surface data output;
fields
the fields to be sampled;

The interpolationScheme includes cellPoint and cellPointFace options in which each polyhedral cell is decomposed into tetrahedra and the sample values are interpolated from values at the tetrahedra vertices. With cellPoint, the tetrahedra vertices include the polyhedron cell centre and 3 face vertices. The vertex coincident with the cell centre inherits the cell centre field value and the other vertices take values interpolated from cell centres. With cellPointFace, one of the tetrahedra vertices is also coincident with a face centre, which inherits field values by conventional interpolation schemes using values at the centres of cells that the face intersects.

The setFormat entry for line sampling includes a raw data format and formats for gnuplot, Grace/xmgr and jPlot graph drawing packages. The data are written into a sets directory within the case directory. The directory is split into a set of time directories and the data files are contained therein. Each data file is given a name containing the field name, the sample set name, and an extension relating to the output format, including .xy for raw data, .agr for Grace/xmgr and .dat for jPlot. The gnuplot format has the data in raw form with an additional commands file, with .gplt extension, for generating the graph. Note that any existing sets directory is deleted when sample is run.

The surfaceFormat entry for surface sampling includes a raw data format and formats for gnuplot, Grace/xmgr and jPlot graph drawing packages. The data are written into a surfaces directory within the case directory. The directory is split into time directories and files are written much as with line sampling.

The fields list contains the fields that the user wishes to sample. The sample utility can parse the following restricted set of functions to enable the user to manipulate vector and tensor fields, e.g. for U:

U.component(n   \relax \special {t4ht=)
writes the n  \relax \special {t4ht=th component of the vector/tensor, n = 0,1 ...  \relax \special {t4ht=;
mag(U)
writes the magnitude of the vector/tensor.

The sets list contains sub-dictionaries of locations where the data is to be sampled. The sub-dictionary is named according to the name of the set and contains a set of entries, also listed in Table 7.4, that describes the locations where the data is to be sampled. For example, a uniform sampling provides a uniform distribution of nPoints sample locations along a line specified by a start and end point. All sample sets are also given: a type; and, means of specifying the length ordinate on a graph by the axis keyword.


Required entries
Sampling type Sample locations name axis start end nPoints points








uniform Uniformly distributed points on a line ∙ \relax \special {t4ht= ∙ \relax \special {t4ht= ∙ \relax \special {t4ht=   ∙ \relax \special {t4ht=          ∙ \relax \special {t4ht=
face Intersection of specified line and cell faces ∙ \relax \special {t4ht= ∙ \relax \special {t4ht= ∙ \relax \special {t4ht=   ∙ \relax \special {t4ht=
midPoint Midpoint between line-face intersections ∙ \relax \special {t4ht= ∙ \relax \special {t4ht= ∙ \relax \special {t4ht=   ∙ \relax \special {t4ht=
midPointAndFace Combination of midPoint and face ∙ \relax \special {t4ht= ∙ \relax \special {t4ht= ∙ \relax \special {t4ht=   ∙ \relax \special {t4ht=
cloud Specified points ∙ \relax \special {t4ht= ∙ \relax \special {t4ht=                 ∙ \relax \special {t4ht=
patchCloud Sample nearest points on selected patches ∙ \relax \special {t4ht= ∙ \relax \special {t4ht=                 ∙ \relax \special {t4ht=
patchSeed Randomly sample on selected patches ∙ \relax \special {t4ht= ∙ \relax \special {t4ht=                 ∙ \relax \special {t4ht=
polyLine Specified points (uses particle tracking) ∙ \relax \special {t4ht= ∙ \relax \special {t4ht=                 ∙ \relax \special {t4ht=
triSurfaceMeshPointSet Sample points on a triangulated surface ∙ \relax \special {t4ht= ∙ \relax \special {t4ht=                 ∙ \relax \special {t4ht=








Entries Description
Options




type Sampling type
see list above
axis Output of sample location x x  \relax \special {t4ht= ordinate
y y  \relax \special {t4ht= ordinate
z z  \relax \special {t4ht= ordinate
xyz xyz \relax \special {t4ht= coordinates
distance distance from point 0
start Start point of sample line
e.g.(0.0 0.0 0.0)
end End point of sample line
e.g.(0.0 2.0 0.0)
nPoints Number of sampling points
e.g.200
points List of sampling points





Table 7.4: Entries within sets sub-dictionaries.

The surfaces list contains sub-dictionaries of locations where the data is to be sampled. The sub-dictionary is named according to the name of the surface and contains a set of entries beginning with the type: either a plane, defined by point and normal direction, with additional sub-dictionary entries specified in Table 7.5; or, a patch, coinciding with an existing boundary patch, with additional sub-dictionary entries specified in Table 7.6.


Keyword Description Options



basePoint Point on plane e.g.(0 0 0)
normalVector Normal vector to plane e.g.(1 0 0)
interpolate Interpolate data? true/false
triangulate Triangulate surface? (optional) true/false




Table 7.5: Entries for a plane in surfaces sub-dictionaries.


Keyword Description Options



patchName Name of patch e.g.movingWall
interpolate Interpolate data? true/false
triangulate Triangulate surface? (optional) true/false




Table 7.6: Entries for a patch in surfaces sub-dictionaries.