NAME

gsudf.gex - Writing Expression Functions as GrADS Scripts

SYNOPSIS

  ga-> display myfunc(args)

where myfunc is implemented in a GrADS script file named myfunc.gsf

DESCRIPTION

Traditionally, there are two kinds of functions in GrADS: script functions and expression functions, and up to now these two did not mix. Scripting functions are user defined and called from any GrADS script. Such functions are not directly available at the command line, or cannot be used inside GrADS expressions. Expression functions are usually used in conjunction with the display and define commands such as

   ga-> display aave(myfunc(u), global)

where aave is an intrinsic function and myfunc is a user defined function.

The dynamic extension gsudf allows you to write expression functions as GrADS script functions. This is better explained with the following examples.

EXAMPLES

Using gsudf for Computing Wind Speed

Let us reimplement the intrinsic function mag which compute the wind speed given the u and v components of the wind; we will call this new function speed. The first step is to create a text file called speed.gsf with the implementation of this function:

   function speed ( u, v )
      expr = 'sqrt(' u '*' u '+' v '*' v ')'
      return expr

Notice that this function simply returns a string which will eventually be evaluated by the GrADS expression parser; more on that later. The second step in the implementation of this function is to add an entry for this function in your User Defined eXtenfion (UDXT) file:

      Type  API   Name      Function       Library
     ------ --- ---------  -----------  --------------
      udf    0    speed      f_gsudf     gsudf.gex.so

The generic handler f_gsudf in the shared library gsudf.gex executes the file speed.gsf, evaluates the string output of this function using the GrADS expression parser and returns the result. The net effect is that speed.gsf, with the help of its agent gsudf, implements a bonafide GrADS expression function.

Finally, you no longer need to initialize the gsudf package in GrADS v2.0.

   ga-> open model.ctl
   ga-> display speed(ua,va)

Returning defined variables

Although your GrADS script must always return a string, it does not mean that all it can do is string maniputation. By using the define command one can always pre-computed intermediate values, and return the name of the defined variable. Here is an example where the dimension environment is modified, a variable defined in this enlarged dimension environment, and then the dimension reset to its original state:

   function x_cdiff ( var, dim )
      'set x 0 74'
      'define gsudf = cdiff('var','dim')'
      'set x 1 73'
      return 'gsudf'

This function enlarges the domain as to avoid missing undefined values on the longitudinal boundaries (but not at the latitudinal boundary.) A more generic version of this function is included with the source distribution for this extension.

Returning an error condition

Returning an empty string will signal an error condition

   function errfunc(arg)
      say 'errfunc: error found, cannot proceed'
      return

FUNCTION PROVIDED

gsudf [ARGUMENTS]

This function is not directly callable as such from GrADS. Rather it works as a proxy for the user defined functions written as GrADS scripts. There 2 steps involved in defining your user defined function through gsudf:

For each function named $func, create a script library file called $func.gsf and placed in a directory where GrADS can locate scripts (for example, in a directory listed in your GASCRP environment variable.) The GrADS script must return a string with a valid GrADS expression, or an empty string in case of an abnormal exit.

Have a corresponding entry in your User Defined eXtension (UDXT) file, e.g.,

 #      A
 #      P   GrADS     Library      Library                 Short
 # Type I  Function   Function      Path                Description
 # ---- - ---------- ---------- -------------- -------------------------------  
   udf  0   speed     f_gsudf    ^gsudf.gex    "The mag() function as gsUDF"

BUGS

There is not much in terms of garbage collection. Any local variable defined by the GrADS script implementing the expression function stays around until explicitly undefined. To minimize memory usage explicitly undefine any variabled you defined, and when defined variables are involved, return your result in defined variable called gsudf.

AUTHOR

Arlindo da Silva (dasilva@opengrads.org)

COPYRIGHT

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

gsudf.gex - Writing Expression Functions as GrADS Scripts