[[sec_sample]]
=== Sampling data

:gnuplot: http://gnuplot.info['gnuplot']
:grace: http://plasma-gate.weizmann.ac.il/Grace['Grace/xmgr']
:jplot: http://jplot.sourceforge.net['JPlot']

{project} provides the `sample` (((`sample` utility)))(((utility,`sample`)))
utility to sample field data, either through a 1D line for plotting on graphs
or a 2D plane for displaying as isosurface images. The sampling locations are
specified for a case through a filename:sampleDict[] dictionary in the case
filename:system[] directory. The data can be written in a range of formats
including well-known graphing packages such as {grace}, {gnuplot} and {jplot}.

The filename:sampleDict[] dictionary can be generated by copying an example
filename:sampleDict[] from the `sample` source code directory at
dirname:applications/utilities/postProcessing/sampling/sample[]. The
dirname:plateHole[] tutorial case in the
dirname:<tutorials>/solidDisplacementFoam[] directory also contains an
example for 1D line sampling:

-------------------------------------------------------------------------------
interpolationScheme cellPoint;

setFormat raw;

sets
(
    leftPatch
    {
        type uniform;
        axis y;
        start ( 0 0.5 0.25 );
        end ( 0 2 0.25 );
        nPoints 100;
    }
);

surfaces ();

fields ( sigmaxx );
-------------------------------------------------------------------------------

[[tab_sampleDict]]
.keyword entries for filename:sampleDict[]
[grid="none",frame="topbot",options="header"]
|==============================================================================
| Keyword | Options | Description
| `interpolationScheme` (((`interpolationScheme` keyword)))
(((keyword,`interpolationScheme`))) | `cell` (((`cell`,keyword entry)))
(((keyword entry,`cell`))) | Cell-centre value assumed constant over cell
|| `cellPoint` (((`cellPoint`,keyword entry)))(((keyword entry,`cellPoint`))) |
Linear weighted interpolation using cell values
|| `cellPointFace` (((`cellPointFace`,keyword entry)))
(((keyword entry,`cellPointFace`))) |  Mixed linear weighted / cell-face
interpolation
| `setFormat` (((`setFormat` keyword)))(((keyword,`setFormat`))) | `raw`
(((`raw`,keyword entry)))(((keyword entry,`raw`))) | Raw ASCII data in columns
|| `gnuplot` (((`gnuplot`,keyword entry)))(((keyword entry,`gnuplot`))) | Data
in `gnuplot` format
|| `xmgr` (((`xmgr`,keyword entry)))(((keyword entry,`xmgr`))) | Data in
`Grace/xmgr` format
|| `jplot` (((`jplot`,keyword entry)))(((keyword entry,`jplot`))) | Data in
`jPlot` format
| `surfaceFormat` (((`surfaceFormat` keyword)))(((keyword,`surfaceFormat`))) |
`null` (((`null`,keyword entry)))(((keyword entry,`null`))) | Suppresses output
|| `foamFile` (((`foamFile`,keyword entry)))(((keyword entry,`foamFile`))) |
filename:points[], filename:faces[], filename:values[] file
|| `dx` (((`dx`,keyword entry)))(((keyword entry,`dx`))) | DX scalar or vector
format
|| `vtk` (((`vtk`,keyword entry)))(((keyword entry,`vtk`))) | VTK ASCII format
|| `raw` (((`raw`,keyword entry)))(((keyword entry,`raw`))) | math:[xyz] values
for use with 'e.g.' `gnuplot splot`
|| `stl` (((`stl`,keyword entry)))(((keyword entry,`stl`))) | ASCII STL; just
surface, no values
| `fields` (((`fields` keyword)))(((keyword,`fields`))) 2+| List of fields to
be sampled, 'e.g.' for velocity `U`:
|| `U` | Writes all components of math:[\U]
| `sets` (((`sets` keyword)))(((keyword,`sets`))) 2+| List of 1D sets
subdictionaries &mdash; see <<tab_sampleSets>>
| `surfaces` (((`surfaces` keyword)))(((keyword,`surfaces`))) 2+| List of 2D
surfaces subdictionaries &mdash; see <<tab_surfacesPlane>> and
<<tab_surfacesPatch>>
|==============================================================================

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 filename: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
filename:.xy[] for raw data, filename:.agr[] for `Grace/xmgr` and
filename:.dat[] for `jPlot`. The `gnuplot` format has the data in raw form with
an additional commands file, with filename:.gplt[] extension, for generating
the graph. 'Note that any existing dirname: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 dirname: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>)+::
  writes the __<n>__th component of the vector/tensor, math:[n=0,1...];
`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 <<tab_sampleSets>>, 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.

[[tab_sampleSets]]
.Entries within `sets` sub-dictionaries
[grid="none",frame="topbot",cols="5,6,1^,1^,1^,1^,2^,2^"]
|==============================================================================
| | 6+^h| Required entries
h| Sampling type h| Sample locations h| `name` h| `axis` h| `start` h| `end` h|
`nPoints` h| `points`
|`uniform` (((`uniform` keyword)))(((keyword,`uniform`))) | Uniformly
distributed points on a line | &bull; | &bull; | &bull; | &bull; | &bull;|
|`face` (((`face` keyword)))(((keyword,`face`))) | Intersection of specified
line and cell faces | &bull; | &bull; | &bull; | &bull; | |
|`midPoint` (((`midPoint` keyword)))(((keyword,`midPoint`))) | Midpoint between
line-face intersections | &bull; | &bull; | &bull; | &bull; | |
|`midPointAndFace` (((`midPointAndFace` keyword)))
(((keyword,`midPointAndFace`))) | Combination of `midPoint` and `face` | &bull;
| &bull; | &bull; | &bull; | |
|`curve` (((`curve` keyword)))(((keyword,`curve`))) | Specified points, tracked
along a curve | &bull; | &bull; | || | &bull;
|`cloud` (((`cloud` keyword)))(((keyword,`cloud`))) | Specified points | &bull;
| &bull; | || | &bull;
h| Entries h| Description 6+<h| Options
| `type` | Sampling type 6+<| see list above
| `axis` | Output of sample location 2+<| `x` (((`x`,keyword entry)))
(((keyword entry,`x`))) 4+<| math:[x] ordinate
|| 2+<| `y`(((`y`,keyword entry)))(((keyword entry,`y`))) 4+<|math:[y] ordinate
|| 2+<| `z`(((`z`,keyword entry)))(((keyword entry,`z`))) 4+<|math:[z] ordinate
|| 2+<| `xyz`(((`xyz`,keyword entry)))(((keyword entry,`xyz`))) 4+<|math:[xyz]
coordinates
|| 2+<| `distance`(((`distance`,keyword entry)))(((keyword entry,`distance`)))
4+<| distance from point 0
| `start` | Start point of sample line 6+<| 'e.g.' `(0.0 0.0 0.0)`
| `end` | End point of sample line 6+<| 'e.g.' `(0.0 2.0 0.0)`
| `nPoints` | Number of sampling points 6+<| 'e.g.' `200`
| `points` | List of sampling points 6+<|
|==============================================================================

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 a
specified in <<tab_surfacesPlane>>; or, a `patch`,(((`patch`,keyword entry)))
(((keyword entry,`patch`))) coinciding with an existing boundary patch, with
additional sub-dictionary entries a specified in <<tab_surfacesPatch>>.

[[tab_surfacesPlane]]
.Entries for a `plane` in `surfaces` sub-dictionaries
[grid="none",frame="topbot",options="header"]
|==============================================================================
| 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`
|==============================================================================

[[tab_surfacesPatch]]
.Entries for a `patch` in `surfaces` sub-dictionaries
[grid="none",frame="topbot",options="header"]
|==============================================================================
| Keyword | Description | Options
| `patchName` | Name of patch | 'e.g.' `movingWall`
| `interpolate` | Interpolate data? | `true`/`false`
| `triangulate` | Triangulate surface? (optional) | `true`/`false`
|==============================================================================
