# GfsFunction

### From Gerris

Revision as of 23:26, 2 August 2007203.58.241.190 (Talk) (added bit about comments in C functions) ← Previous diff |
Current revisionPopinet (Talk | contribs) (→Other pre-defined functions) |
||

Line 1: |
Line 1: | ||

- | Functions can be used in most objects which require a numerical parameter. A function can be a constant or a piece of C code taking coordinates (x,y,z), time t or any of the domain variables as arguments and returning a floating-point value. | + | Functions can be used in most objects which require a numerical parameter. A function can be a constant or a piece of C code taking coordinates (x,y,z), time t or any of the [[domain variables]] as arguments and returning a floating-point value. Note that the values appearing in (and returned by) a GfsFunction are always ''local'' values (i.e. the value at a given position (x,y,z) and given time t). |

- | The syntax in parameter files is as follows: | + | The syntax in parameter files is: |

-1.78e-3 | -1.78e-3 | ||

Line 18: |
Line 18: | ||

40.*(P - 1.) | 40.*(P - 1.) | ||

- | or a GTS file | + | or a GTS/CGD file |

myfunction.gts | myfunction.gts | ||

+ | |||

+ | == GTS files == | ||

The GTS file must be a planar (preferably Delaunay) triangulation of a set of points. The value of the function at a given (x,y) coordinate is then calculated by computing the z-coordinate of the intersection of a vertical line passing through the point at (x,y,0) with the triangulation defined by the GTS file. | The GTS file must be a planar (preferably Delaunay) triangulation of a set of points. The value of the function at a given (x,y) coordinate is then calculated by computing the z-coordinate of the intersection of a vertical line passing through the point at (x,y,0) with the triangulation defined by the GTS file. | ||

+ | |||

+ | == Cartesian Grid Data (CGD) files == | ||

+ | |||

+ | Cartesian Grid Data files can be specified as | ||

+ | |||

+ | mydata.cgd | ||

+ | |||

+ | Note that the extension must be <code>.cgd</code>. | ||

+ | |||

+ | The CGD file contains data defined on a Cartesian grid and can be used with 1 to 4 space/time dimensions. | ||

+ | |||

+ | The first line of the file defines the structure of the grid for example : | ||

+ | |||

+ | 3 x y t | ||

+ | |||

+ | Here <code>3</code> is the number of dimensions, <code>x</code>, <code>y</code> and <code>t</code> define the structure of the data: 2 spatial dimensions and 1 temporal dimension. | ||

+ | |||

+ | Then the number of points for each dimension must be specified (e.g. in a 2x2x2 mesh, the number of points for each dimension is 2): | ||

+ | |||

+ | 2 2 2 | ||

+ | |||

+ | The following 3 lines contain the space-separated values defining the positions of each Cartesian grid line in each of the dimensions. Note that these coordinates need to be in increasing order. | ||

+ | |||

+ | The rest of the file contains the values at each grid point in "C-array order", i.e., with the rightmost dimension varying fastest. | ||

+ | |||

+ | The value of the function at a given (x,y,t) coordinate is then calculated by tri-linear interpolation on the Cartesian grid. | ||

+ | |||

+ | == Computing gradients and fluxes == | ||

Gradients of variables can be computed using the <code>dx()</code>, <code>dy()</code> and <code>dz()</code> functions. For example, the z-component of the vorticity would be computed as: | Gradients of variables can be computed using the <code>dx()</code>, <code>dy()</code> and <code>dz()</code> functions. For example, the z-component of the vorticity would be computed as: | ||

(dx("V") - dy("U")) | (dx("V") - dy("U")) | ||

+ | |||

+ | Gradients on [[GfsSolid|embedded boundaries]] can be computed using the <code>dsx()</code>, <code>dsy()</code> and <code>dsz()</code> functions. | ||

+ | |||

+ | The flux of a given quantity "T" through the fragment of embedded boundary contained in a given cell can be computed using <code>flux("T")</code>. | ||

+ | |||

+ | To obtain the corresponding derivative of "T" normal to the boundary one could use <code>(S > 0. ? flux("T")/S : 0)</code> where the [[w:Conditional_operator|C ternary operator]] has been used to avoid division by zero, and <code>S</code> is the surface area of the fragment of embedded boundary (one of the predefined [[domain_variables#derived_variables|derived variables]]). | ||

+ | |||

+ | == Other pre-defined functions == | ||

+ | |||

+ | ;<source lang=c>gboolean overlaps (double x1, double y1, double x2, double y2)</source>: returns <code>TRUE</code> if a cell overlaps the box defined by its lower-left (resp. upper-right) corner <code>(x1,y1)</code> (resp. <code>(x2,y2)</code>). This can be used for example as a <code>condition</code> for [[GfsOutputScalar]]. | ||

== More details on C functions == | == More details on C functions == | ||

- | Comments should use the C syntax; i.e. opening <code>/*</code> and closing | + | [[Comments]] should use the C syntax; i.e. opening <code>/*</code> and closing |

<code>*/</code> not necessarily on the same line rather than the usual parameter file syntax of a line beginning with a <code>#</code>. This is to allow the use of [http://en.wikipedia.org/wiki/C_preprocessor C preprocessor] directives in C functions in GfsFunctions. | <code>*/</code> not necessarily on the same line rather than the usual parameter file syntax of a line beginning with a <code>#</code>. This is to allow the use of [http://en.wikipedia.org/wiki/C_preprocessor C preprocessor] directives in C functions in GfsFunctions. | ||

Example: | Example: | ||

* [http://gfs.sourceforge.net/examples/examples/logo/logo.gfs.html Coalescence of a pair of Gaussian vortices (Gerris logo)], in the [[GfsInitVorticity|InitVorticity]] command. | * [http://gfs.sourceforge.net/examples/examples/logo/logo.gfs.html Coalescence of a pair of Gaussian vortices (Gerris logo)], in the [[GfsInitVorticity|InitVorticity]] command. |

## Current revision

Functions can be used in most objects which require a numerical parameter. A function can be a constant or a piece of C code taking coordinates (x,y,z), time t or any of the domain variables as arguments and returning a floating-point value. Note that the values appearing in (and returned by) a GfsFunction are always *local* values (i.e. the value at a given position (x,y,z) and given time t).

The syntax in parameter files is:

-1.78e-3

or a C function

{ double a = sin (x + y); double b = cos (x - z); double c = sin (M_PI*t); return a + b + c; }

or a C expression

40.*(P - 1.)

or a GTS/CGD file

myfunction.gts

## Contents |

## GTS files

The GTS file must be a planar (preferably Delaunay) triangulation of a set of points. The value of the function at a given (x,y) coordinate is then calculated by computing the z-coordinate of the intersection of a vertical line passing through the point at (x,y,0) with the triangulation defined by the GTS file.

## Cartesian Grid Data (CGD) files

Cartesian Grid Data files can be specified as

mydata.cgd

Note that the extension must be `.cgd`

.

The CGD file contains data defined on a Cartesian grid and can be used with 1 to 4 space/time dimensions.

The first line of the file defines the structure of the grid for example :

3 x y t

Here `3`

is the number of dimensions, `x`

, `y`

and `t`

define the structure of the data: 2 spatial dimensions and 1 temporal dimension.

Then the number of points for each dimension must be specified (e.g. in a 2x2x2 mesh, the number of points for each dimension is 2):

2 2 2

The following 3 lines contain the space-separated values defining the positions of each Cartesian grid line in each of the dimensions. Note that these coordinates need to be in increasing order.

The rest of the file contains the values at each grid point in "C-array order", i.e., with the rightmost dimension varying fastest.

The value of the function at a given (x,y,t) coordinate is then calculated by tri-linear interpolation on the Cartesian grid.

## Computing gradients and fluxes

Gradients of variables can be computed using the `dx()`

, `dy()`

and `dz()`

functions. For example, the z-component of the vorticity would be computed as:

(dx("V") - dy("U"))

Gradients on embedded boundaries can be computed using the `dsx()`

, `dsy()`

and `dsz()`

functions.

The flux of a given quantity "T" through the fragment of embedded boundary contained in a given cell can be computed using `flux("T")`

.

To obtain the corresponding derivative of "T" normal to the boundary one could use `(S > 0. ? flux("T")/S : 0)`

where the C ternary operator has been used to avoid division by zero, and `S`

is the surface area of the fragment of embedded boundary (one of the predefined derived variables).

## Other pre-defined functions

gboolean overlaps (double x1, double y1, double x2, double y2)

- returns
`TRUE`

if a cell overlaps the box defined by its lower-left (resp. upper-right) corner`(x1,y1)`

(resp.`(x2,y2)`

). This can be used for example as a`condition`

for GfsOutputScalar.

## More details on C functions

Comments should use the C syntax; i.e. opening `/*`

and closing
`*/`

not necessarily on the same line rather than the usual parameter file syntax of a line beginning with a `#`

. This is to allow the use of C preprocessor directives in C functions in GfsFunctions.

Example:

- Coalescence of a pair of Gaussian vortices (Gerris logo), in the InitVorticity command.